---
title: Local Development & Contributing Guide
description: Step-by-step developer guide for building, testing, and extending VertiWiki from source.
tags: [vertiwiki, development, contributing, testing, vite, typescript]
---

# Local Development & Contributing Guide

> For the complete documentation index and agent navigation, see [llms.txt](/llms.txt).

This guide walks you through setting up a local development environment, compiling the single-file distribution, running automated tests, and creating custom plugins.

---

## 🛠️ Prerequisites

- **Node.js**: Version `22.0.0` or later.
- **Package Manager**: `npm`, `pnpm`, or `bun`.
- **Git**: For source version control.

---

## 🚀 Setting Up the Development Workspace

### 1. Clone the Engine Repository
```bash
git clone https://github.com/Octadira/vertiwiki.git
cd vertiwiki
```

### 2. Install Dependencies
```bash
npm install
```

### 3. Start the Live Development Server
```bash
npm run dev
```
Vite will start a hot-module-replacement (HMR) server at `http://localhost:5173`. Any changes made to files in `src/` or `demo/` will instantly update in the browser.

---

## 🧪 Testing Suite (Vitest)

VertiWiki maintains 100% test coverage across core modules and plugins.

```bash
# Run all unit tests once
npm test

# Run strict TypeScript typechecking
npm run typecheck

# Run tests in watch mode during development
npx vitest

# Run tests with coverage report
npx vitest run --coverage
```

### Key Test Suites:
- `tests/security.test.ts`: Verifies iframe sandboxing (`allow-presentation`), dangerous URI neutralization (`javascript:`, `vbscript:`), and DOM safety.
- `tests/router-i18n.test.ts`: Validates hash path normalization, subfolder resource resolution, and locale switches.
- `tests/pipeline.test.ts`: Verifies middleware order of execution (`beforeParse`, `afterParse`, `afterRender`).
- `tests/parser.test.ts`: Ensures YAML frontmatter extraction, auto-closing code fences, and DOMPurify sanitization.
- `tests/plugins-markup.test.ts`: Verifies wikilinks, callout badges, tabs, and math rendering.

---

## 📦 Building the Production Distribution

To bundle the entire application into a single, standalone HTML asset:

```bash
npm run build
```

This pipeline executes:
1. TypeScript typecheck validation (`tsc --noEmit`).
2. Vite asset compilation and bundling with `vite-plugin-singlefile`.
3. Inlines all fonts, SVGs, styles, and scripts into a standalone document.
4. The `closeBundle()` hook natively writes both `dist/index.html` and `dist/vertiwiki.html` directly, eliminating OS-dependent shell copy commands (`cp`) for 100% cross-platform compatibility across Windows, macOS, and Linux.

---

## 🎨 Developing a Custom Theme Preset

Custom themes reside in `themes/<name>.json`. You can design and test a custom theme without editing core code:

1. Create `themes/my-brand.json`:
```json
{
  "id": "my-brand",
  "name": "My Brand Theme",
  "previewColor": "#0ea5e9",
  "light": {
    "background": "#ffffff",
    "foreground": "#0f172a",
    "primary": "#0ea5e9",
    "border": "#e2e8f0"
  },
  "dark": {
    "background": "#0b1120",
    "foreground": "#f8fafc",
    "primary": "#38bdf8",
    "border": "#1e293b"
  }
}
```

2. Register it in `config.json`:
```json
{
  "customThemes": ["themes/my-brand.json"],
  "themePreset": "my-brand"
}
```

3. Reload your browser to inspect the applied tokens.