Getting Started

Say hello to Runiq!

This guide will help you get Runiq up and running in minutes.

Installation

Prerequisites

• Node.js >= 20.19 (or >= 22.12)
• pnpm >= 8.15.0 (recommended) or npm

Install via pnpm

# Install pnpm globally if you haven't
npm install -g pnpm

# Clone the repository
git clone https://github.com/jgreywolf/runiq.git
cd runiq

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests to verify
pnpm test

Install via npm

# Clone and install
git clone https://github.com/jgreywolf/runiq.git
cd runiq
npm install

# Build and test
npm run build
npm test

Project Structure

Runiq/
├── packages/              # Core packages
│   ├── core/             # Types, shapes, registries
│   ├── parser-dsl/       # Langium parser
│   ├── layout-base/      # ELK layout engine
│   ├── renderer-svg/     # SVG renderer
│   ├── io-json/          # JSON I/O
│   ├── export-spice/     # SPICE exporter
│   ├── export-verilog/   # Verilog exporter
│   ├── export-latex/     # LaTeX exporter
│   ├── export-simulink/  # Simulink exporter
│   └── cli/              # CLI tool
├── apps/
│   └── editor/           # SvelteKit editor
├── examples/             # Example diagrams
└── docs/                 # Documentation

Your First Diagram

1. Create a .runiq file

Create a file named hello.runiq:

diagram "Hello Runiq" direction: TB

shape Start as @rounded label: "Start"
shape Process as @rect label: "Process Data"
shape Decision as @rhombus label: "Valid?"
shape Success as @hex label: "Success"
shape Error as @doc label: "Error"

Start -> Process
Process -> Decision
Decision[yes] -> Success
Decision[no] -> Error

2. Generate SVG (via CLI - coming soon)

# Once CLI is ready
runiq hello.runiq -o hello.svg

3. Use in Code

import { parse } from '@runiq/parser-dsl';
import { layoutDiagram } from '@runiq/layout-base';
import { renderSvg } from '@runiq/renderer-svg';
import { readFileSync, writeFileSync } from 'fs';

// Read the .runiq file
const dslContent = readFileSync('hello.runiq', 'utf-8');

// Parse
const parseResult = parse(dslContent);
if (!parseResult.success) {
  console.error('Parse errors:', parseResult.errors);
  process.exit(1);
}

// Layout
const diagram = parseResult.document!.diagrams[0];
const laidOut = await layoutDiagram(diagram, {
  direction: 'TB',
  spacing: 80,
});

// Render
const result = renderSvg(diagram, laidOut, {
  title: 'Hello Runiq',
});

// Save
writeFileSync('hello.svg', result.svg, 'utf-8');
console.log('✅ Generated hello.svg');

Development Workflow

Running Tests

# Run all tests
pnpm test

# Run tests for specific package
cd packages/core && pnpm test

# Watch mode for development
cd packages/core && pnpm test:watch

Building Packages

# Build all packages
pnpm -r build

# Build specific package
cd packages/core && pnpm build

# Watch mode for development
cd packages/core && pnpm build:watch

Running the Editor

# Start the SvelteKit editor
cd apps/editor
pnpm dev

# Open http://localhost:5173

Common Tasks

Adding a New Shape

1. Create shape definition in packages/core/src/shapes/my-shape.ts
2. Register in packages/core/src/shapes/index.ts
3. Add tests in packages/core/src/__tests__/my-shape.test.ts
4. Update documentation

Creating an Export Format

1. Create package: packages/export-myformat/
2. Implement exporter following existing patterns
3. Add tests
4. Document format and usage

Contributing

See Contributing Guide for:

• Code style guidelines
• Pull request process
• Test requirements
• Documentation standards

Troubleshooting

Build Errors

Problem: Cannot find module '@runiq/core'

Solution: Build dependencies first:

cd packages/core && pnpm build

Test Failures

Problem: Tests failing after changes

Solution: Rebuild and re-run:

pnpm -r build
pnpm test

Parser Errors

Problem: Langium parser not working

Solution: Regenerate Langium artifacts:

cd packages/parser-dsl
pnpm langium:generate
pnpm build

Next Steps

• Quick Start Tutorial → - Build your first diagram
• Core Concepts → - Understand shapes and edges
• Examples → - See real-world diagrams
• API Reference → - Deep dive into the API

Getting Help

• GitHub Issues - Bug reports and feature requests
• Discussions - Questions and community
• Contributing - How to contribute

---

Development Setup Complete?

Once you have Runiq running, try the Quick Start → tutorial to create your first diagram!