Runiq

A text-based diagram language that parses .runiq files and renders them to SVG.

Runiq is for keeping diagrams in source control. Write a diagram as text, render it as SVG, and use the same source in docs, build scripts, web apps, or editor tooling.

Links

• Documentation
• Guide
• Examples
• DSL Reference
• Web SDK
• CLI

What It Supports

Runiq has a general diagram profile plus specialized profiles for common diagram domains.

• Flowcharts, architecture diagrams, containers, C4, UML-style diagrams, data flow diagrams, ERDs, requirements diagrams, threat models
• Sequence diagrams, state machines, activity diagrams, BPMN, railroad diagrams
• Mindmaps, timelines, Wardley maps, kanban boards, Git graphs, treemaps, pedigrees
• Charts, Sankey diagrams, Venn diagrams, pyramid diagrams, weighted/force-directed graphs
• Electrical, digital, pneumatic, hydraulic, HVAC, control, P&ID, block, kinematic, and quantum diagrams
• Glyphsets: SmartArt-style templates such as funnels, cycles, pyramids, matrices, org charts, and process layouts

Output is SVG. Some profiles also export to domain formats such as SPICE, Verilog, BPMN XML, LaTeX/TikZ, and Simulink MDL.

Install

For web apps:

pnpm add @runiq/web

For CLI use:

pnpm add -g @runiq/cli

For local repo development:

git clone https://github.com/quipolabs/runiq.git
cd runiq
pnpm install
pnpm build
pnpm test

Requirements: Node.js >=20.13.0 <21 || >=22.12.0, pnpm 8.15.0.

Quick Start

Create a .runiq file:

diagram "Auth Flow" {
  direction LR

  style decision fillColor:"#fff7e6" strokeColor:"#aa7700"

  shape user as @actor label:"Visitor"
  shape landing as @rounded label:"Landing Page"
  shape check as @rhombus label:"Signed up?" style:decision
  shape welcome as @hexagon label:"Welcome"

  user -> landing label:"visits"
  landing -> check
  check -yes-> welcome
}

Render it with the CLI:

runiq render auth-flow.runiq -o auth-flow.svg

Or render it from TypeScript:

import { renderRuniqToSvg } from '@runiq/web';

const { svg, warnings } = await renderRuniqToSvg(source);

@runiq/web can run in the browser or on the server. See Server-Side SVG Rendering for Node/API route examples.

Specialized Example

sequence "Login" {
  participant "User" as actor
  participant "API" as control
  participant "Database" as database

  User -> API: "POST /login"
  API -> Database: "lookup user"
  Database --> API: "user record"
  API --> User: "200 OK"
}

Use the same renderRuniqToSvg helper for supported specialized profiles.

Packages

Package	npm	Purpose
@runiq/web		Browser/server SDK for parsing and rendering
@runiq/cli		Command-line rendering and export
@runiq/core		Core AST types, registries, shapes, themes
@runiq/parser-dsl		Langium-based DSL parser
@runiq/layout-base		Layout interfaces and ELK adapter
@runiq/renderer-svg		SVG renderer for diagram profiles
@runiq/renderer-schematic		Schematic renderer for engineering profiles
@runiq/io-json		JSON import/export helpers
@runiq/glyphsets		Built-in SmartArt-style diagram patterns
@runiq/icons-brand		Brand icon provider
@runiq/icons-fontawesome		Font Awesome icon provider
@runiq/icons-iconify		Iconify-style icon provider
@runiq/data-loader		JSON/CSV data loading
@runiq/export-spice		SPICE netlist export
@runiq/export-verilog		Verilog export
@runiq/export-bpmn		BPMN XML export/import
@runiq/export-latex		LaTeX/TikZ export
@runiq/export-simulink		Simulink MDL export

Development

pnpm install
pnpm build
pnpm test
pnpm docs:dev
pnpm dev

Useful scripts:

• pnpm build builds all packages.
• pnpm test builds and runs the package test suites.
• pnpm docs:dev starts the VitePress docs site.
• pnpm dev starts the editor app.
• pnpm generate-svgs regenerates example SVG outputs.

Project Layout

apps/editor                 SvelteKit editor
docs                        VitePress documentation
examples                    Example .runiq files
packages/core               Shared types, registries, shapes, themes
packages/parser-dsl         Langium parser
packages/layout-base        Layout engine adapter
packages/renderer-svg       SVG renderers
packages/renderer-schematic Schematic renderers
packages/web                Browser/server SDK
packages/cli                CLI
packages/export-*           Domain export packages

License

MIT. See LICENSE.

Acknowledgments

• Langium for language tooling
• Eclipse Layout Kernel for graph layout
• VitePress for documentation
• Vitest for testing