---
title: Ghid de Dezvoltare Locală & Contribuție
description: Ghid pas cu pas pentru compilarea, testarea și extinderea nucleului VertiWiki din codul sursă.
tags: [vertiwiki, dezvoltare, contributie, testare, vite, typescript, romana]
---

# Ghid de Dezvoltare Locală & Contribuție

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

Acest ghid descrie configurarea mediului local de lucru, compilarea pachetului autonom, rularea testelor automate și adăugarea de noi funcționalități în VertiWiki.

---

## 🛠️ Cerințe Preliminare

- **Node.js**: Versiunea `22.0.0` sau mai recentă.
- **Manager de Pachete**: `npm`, `pnpm` sau `bun`.
- **Git**: Pentru controlul versiunilor.

---

## 🚀 Configurarea Mediului de Dezvoltare

### 1. Clonați Depozitul
```bash
git clone https://github.com/Octadira/vertiwiki.git
cd vertiwiki
```

### 2. Instalați Dependențele
```bash
npm install
```

### 3. Porniți Serverul Local de Dezvoltare
```bash
npm run dev
```
Vite va deschide un server HMR la adresa `http://localhost:5173`. Orice modificare în `src/` se actualizează instantaneu în browser.

---

## 🧪 Suita de Teste Automate (Vitest)

VertiWiki menține acoperire de 100% pentru modulele de bază și plugin-uri:

```bash
# Rulare toate testele o singură dată
npm test

# Verificare strictă a tipurilor TypeScript
npm run typecheck

# Rulare teste în mod interactiv watch
npx vitest

# Generare raport de acoperire cod
npx vitest run --coverage
```

### Fișiere Cheie de Test:
- `tests/security.test.ts`: Validare sandboxing iframe (`allow-presentation`), neutralizare URI (`javascript:`, `vbscript:`) și siguranță tipuri DOM.
- `tests/router-i18n.test.ts`: Validare rutare hash, rezoluție subdirectoare și comutare limbi.
- `tests/pipeline.test.ts`: Verificare ordine execuție hook-uri middleware.
- `tests/parser.test.ts`: Extragere YAML frontmatter, închidere cod fences și igienizare DOMPurify.
- `tests/plugins-markup.test.ts`: Wikilinks, callouts, tabs și randare matematică.

---

## 📦 Compilarea Distribuției de Producție

Pentru a genera fișierul HTML unic și complet:

```bash
npm run build
```

Acest pas execută:
1. Validarea tipurilor TypeScript (`tsc --noEmit`).
2. Împachetarea resurselor prin `vite-plugin-singlefile`.
3. Hook-ul `closeBundle()` din Vite scrie nativ ambele fișiere de distribuție, eliminând comenzile shell specifice OS (`cp`) pentru compatibilitate 100% pe Windows, macOS și Linux:
   - `dist/index.html`
   - `dist/vertiwiki.html`

---

## 🎨 Crearea unei Teme Personalizate

Temele sunt stocate în fișiere JSON în `themes/<nume>.json`:

1. Creați `themes/brandul-meu.json`:
```json
{
  "id": "brandul-meu",
  "name": "Tema Mea",
  "previewColor": "#0ea5e9",
  "light": {
    "background": "#ffffff",
    "foreground": "#0f172a",
    "primary": "#0ea5e9",
    "border": "#e2e8f0"
  },
  "dark": {
    "background": "#0b1120",
    "foreground": "#f8fafc",
    "primary": "#38bdf8",
    "border": "#1e293b"
  }
}
```

2. Adăugați tema în `config.json`:
```json
{
  "customThemes": ["themes/brandul-meu.json"],
  "themePreset": "brandul-meu"
}
```