Development Guide

This guide covers setting up Wire-DSL for development and contributing to the project.

Project Overview

Wire-DSL is a monorepo using Turbo, TypeScript, and pnpm. It consists of:

• @wire-dsl/engine – Parser, IR generator, layout engine, SVG renderer
• @wire-dsl/exporters – PNG, PDF, SVG export (uses Playwright)
• @wire-dsl/cli – Command-line tool for rendering wireframes
• @wire-dsl/editor-ui – Reusable React component library
• @wire-dsl/web – Web editor (React + Monaco)
• apps/docs – Astro Starlight documentation site
• apps/web – Web editor application

---

Prerequisites

• Node.js 20.x or later (check with node --version)
• pnpm 8.x or later (install with npm install -g pnpm)
• Git for version control
• A code editor (VS Code recommended)

---

Initial Setup

1. Clone the Repository

git clone https://github.com/wire-dsl/wire-dsl.git
cd wire-dsl

2. Install Dependencies

pnpm install

This installs all workspace dependencies and uses Turbo for intelligent caching.

3. Verify Installation

pnpm lint
pnpm test

---

Monorepo Commands

Build All Packages

pnpm build

Compiles TypeScript, bundles outputs. Uses Turbo cache for speed.

Development Mode (Watch)

pnpm dev

Starts all watch tasks simultaneously. Changes auto-rebuild.

Run Tests

pnpm test

Runs Vitest across all packages. Filter with --filter:

pnpm test --filter @wire-dsl/engine

Lint Code

pnpm lint
pnpm lint:fix

Uses ESLint. Fix automatically or review violations.

Format Code

pnpm format

Uses Prettier to format all files.

---

Package-Specific Development

Core Engine (@wire-dsl/engine)

Directory: packages/engine/

Start Development:

cd packages/engine
pnpm dev

Key Files:

• src/parser/ – Chevrotain grammar and lexer
• src/ir/ – IR structure and generation
• src/layout/ – Layout calculation engine
• src/renderer/ – SVG and PNG rendering
• src/index.ts – Public API exports

Test Engine:

pnpm test --filter @wire-dsl/engine

Web Editor (@wire-dsl/web)

Directory: apps/web/

Start Dev Server:

cd apps/web
pnpm dev

Opens at http://localhost:5173

Key Files:

• src/components/ – Editor UI components
• src/hooks/ – React hooks (useEditor, useTheme, etc.)
• src/pages/ – Route pages
• src/layout/ – Main editor layout

Features:

• Monaco code editor on left
• Live preview on right
• Theme/component reference on top right
• Keyboard shortcuts (Ctrl+Enter to preview)

CLI (@wire-dsl/cli)

Directory: packages/cli/

Test CLI:

pnpm cli validate examples/simple-dashboard.wire
pnpm cli render-svg examples/simple-dashboard.wire output.svg

Key Commands:

• validate – Check syntax and semantics
• render-svg – Generate SVG output
• render-png – Generate PNG output (requires Playwright)
• render-pdf – Generate PDF output (requires Playwright)

---

File Organization

Wire-DSL/
├── .ai/                          # AI development guidance
├── .github/                       # GitHub workflows, templates
├── docs/                          # Public documentation sources
├── specs/                         # Technical specifications
│   ├── IR-CONTRACT-EN.md
│   ├── LAYOUT-ENGINE-EN.md
│   └── VALIDATION-RULES-EN.md
├── examples/                      # Example .wire files
├── packages/
│   ├── engine/                    # Core parser, IR, layout, renderer
│   │   ├── src/
│   │   │   ├── parser/
│   │   │   ├── ir/
│   │   │   ├── layout/
│   │   │   └── renderer/
│   │   ├── tests/
│   │   └── package.json
│   ├── cli/                       # Command-line interface
│   │   ├── src/
│   │   └── tests/
│   ├── web/                       # Web editor
│   │   ├── src/
│   │   └── package.json
│   ├── editor-ui/                 # Reusable UI components
│   │   ├── src/
│   │   └── package.json
│   └── exporters/                 # PNG, PDF export
├── apps/
│   ├── docs/                      # Astro Starlight docs
│   └── web/                       # Web editor app
├── package.json                   # Root workspace
├── pnpm-workspace.yaml            # Monorepo config
└── turbo.json                     # Turbo build config

---

Common Development Tasks

Adding a New Component

1. Define in Engine (packages/engine/src/parser/grammar.ts)

   // Add to component types
   export type ComponentType = "Button" | "Input" | "YourNewComponent";

2. Add SVG Renderer (packages/engine/src/renderer/components/)

   export function renderYourNewComponent(node: ComponentNode): string {
     // SVG rendering logic
   }

3. Test Parsing & Rendering

   pnpm test --filter @wire-dsl/engine

4. Update Documentation (docs/COMPONENTS-REFERENCE.md)

Adding a CLI Command

1. Define Command (packages/cli/src/commands/)
2. Register in CLI (packages/cli/src/index.ts)
3. Test

   pnpm cli your-command --help

Updating the Web Editor

1. Modify Component (apps/web/src/components/)
2. Test Live

   pnpm dev --filter @wire-dsl/web

3. Test Build

   pnpm build --filter @wire-dsl/web

---

Testing

Run All Tests

pnpm test

Run Specific Package

pnpm test --filter @wire-dsl/engine

Watch Mode

pnpm test -- --watch

Coverage Report

pnpm test -- --coverage

Tests use Vitest. Key test locations:

• packages/engine/tests/
• packages/cli/tests/

---

Code Quality

Type Checking

pnpm typecheck

Checks all TypeScript files. Project uses strict mode.

Linting

pnpm lint
pnpm lint:fix

Uses ESLint with TypeScript support. Rules in .eslintrc.json.

Formatting

pnpm format

Uses Prettier. Config in prettier.config.js.

---

Git Workflow

Creating a Feature Branch

git checkout -b feature/my-feature

Branch naming: feature/, fix/, docs/, chore/

Before Committing

pnpm lint:fix
pnpm format
pnpm test

Ensures quality before pushing.

Creating a Pull Request

1. Push your branch
2. Open PR against main
3. Provide clear description
4. Link any related issues
5. Ensure CI passes
6. Request review

---

Performance Tips

Turbo Cache

Turbo caches build results. To clear cache:

pnpm turbo clean

Selective Builds

Build only changed packages:

pnpm build --filter=[HEAD^]

Filter to Specific Package

pnpm test --filter @wire-dsl/engine
pnpm dev --filter @wire-dsl/web

---

Troubleshooting

Dependencies Won’t Install

rm -rf node_modules pnpm-lock.yaml
pnpm install

Build Fails

pnpm clean
pnpm install
pnpm build

Tests Timeout

Increase timeout in test file:

describe("My Tests", { timeout: 10000 }, () => {
  // ...
});

Port Already in Use

If 5173 is taken:

pnpm dev --filter @wire-dsl/web -- --port 3000

---

Documentation Updates

All documentation source files are in docs/:

• DSL-SYNTAX.md – Language grammar
• COMPONENTS-REFERENCE.md – All components
• ARCHITECTURE.md – System design
• See DOCUMENTATION-INDEX.md for full list

When changing behavior, update corresponding doc.

---

Creating Issues and PRs

Before Opening an Issue

1. Search existing issues (may be duplicate)
2. Check ROADMAP.md for planned work
3. Provide detailed reproduction steps

PR Requirements

• Clear, descriptive title
• Link related issues
• Describe changes
• Ensure tests pass
• Update docs if needed

---

Architecture Overview

Wire-DSL processes wireframes through 7 layers:

1. Lexer – Tokenization
2. Parser – AST generation
3. IR Generator – Semantic structure
4. Validation – Syntax & semantic checks
5. Layout Engine – Size calculation
6. SVG Renderer – Vector output
7. Exporters – PNG/PDF conversion

See Architecture for details.

---

Getting Help

• Check Development Guide (this file)
• Review Architecture
• Search existing issues
• Read MONOREPO.md for project structure
• Check package-specific README.md files

---

Next Steps

• Review the Architecture Guide
• Read the DSL Syntax
• Explore example files
• Start with good first issues