https://github.com/quipolabs/runiq
https://github.com/quipolabs/runiq
diagram-as-code diagramming diagrams-as-code
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/quipolabs/runiq
- Owner: quipolabs
- Created: 2025-10-15T05:36:22.000Z (8 months ago)
- Default Branch: develop
- Last Pushed: 2026-04-16T23:06:05.000Z (2 months ago)
- Last Synced: 2026-04-16T23:14:04.356Z (2 months ago)
- Topics: diagram-as-code, diagramming, diagrams-as-code
- Language: TypeScript
- Homepage: https://www.runiq.org
- Size: 60.6 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
# Runiq
A text-based diagram language that parses `.runiq` files and renders them to SVG.
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://runiq.org)
[](https://www.npmjs.com/package/@runiq/web)
[](https://www.npmjs.com/package/@runiq/cli)
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](https://runiq.org)
- [Guide](https://runiq.org/guide/getting-started)
- [Examples](https://runiq.org/examples/)
- [DSL Reference](https://runiq.org/reference/dsl)
- [Web SDK](./packages/web)
- [CLI](./packages/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:
```bash
pnpm add @runiq/web
```
For CLI use:
```bash
pnpm add -g @runiq/cli
```
For local repo development:
```bash
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:
```runiq
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:
```bash
runiq render auth-flow.runiq -o auth-flow.svg
```
Or render it from TypeScript:
```ts
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](https://runiq.org/guide/server-side-rendering) for Node/API route examples.
## Specialized Example
```runiq
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`](./packages/web) | [](https://www.npmjs.com/package/@runiq/web) | Browser/server SDK for parsing and rendering |
| [`@runiq/cli`](./packages/cli) | [](https://www.npmjs.com/package/@runiq/cli) | Command-line rendering and export |
| [`@runiq/core`](./packages/core) | [](https://www.npmjs.com/package/@runiq/core) | Core AST types, registries, shapes, themes |
| [`@runiq/parser-dsl`](./packages/parser-dsl) | [](https://www.npmjs.com/package/@runiq/parser-dsl) | Langium-based DSL parser |
| [`@runiq/layout-base`](./packages/layout-base) | [](https://www.npmjs.com/package/@runiq/layout-base) | Layout interfaces and ELK adapter |
| [`@runiq/renderer-svg`](./packages/renderer-svg) | [](https://www.npmjs.com/package/@runiq/renderer-svg) | SVG renderer for diagram profiles |
| [`@runiq/renderer-schematic`](./packages/renderer-schematic) | [](https://www.npmjs.com/package/@runiq/renderer-schematic) | Schematic renderer for engineering profiles |
| [`@runiq/io-json`](./packages/io-json) | [](https://www.npmjs.com/package/@runiq/io-json) | JSON import/export helpers |
| [`@runiq/glyphsets`](./packages/glyphsets) | [](https://www.npmjs.com/package/@runiq/glyphsets) | Built-in SmartArt-style diagram patterns |
| [`@runiq/icons-brand`](./packages/icons-brand) | [](https://www.npmjs.com/package/@runiq/icons-brand) | Brand icon provider |
| [`@runiq/icons-fontawesome`](./packages/icons-fontawesome) | [](https://www.npmjs.com/package/@runiq/icons-fontawesome) | Font Awesome icon provider |
| [`@runiq/icons-iconify`](./packages/icons-iconify) | [](https://www.npmjs.com/package/@runiq/icons-iconify) | Iconify-style icon provider |
| [`@runiq/data-loader`](./packages/data-loader) | [](https://www.npmjs.com/package/@runiq/data-loader) | JSON/CSV data loading |
| [`@runiq/export-spice`](./packages/export-spice) | [](https://www.npmjs.com/package/@runiq/export-spice) | SPICE netlist export |
| [`@runiq/export-verilog`](./packages/export-verilog) | [](https://www.npmjs.com/package/@runiq/export-verilog) | Verilog export |
| [`@runiq/export-bpmn`](./packages/export-bpmn) | [](https://www.npmjs.com/package/@runiq/export-bpmn) | BPMN XML export/import |
| [`@runiq/export-latex`](./packages/export-latex) | [](https://www.npmjs.com/package/@runiq/export-latex) | LaTeX/TikZ export |
| [`@runiq/export-simulink`](./packages/export-simulink) | [](https://www.npmjs.com/package/@runiq/export-simulink) | Simulink MDL export |
## Development
```bash
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
```txt
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](./LICENSE).
## Acknowledgments
- [Langium](https://langium.org/) for language tooling
- [Eclipse Layout Kernel](https://www.eclipse.org/elk/) for graph layout
- [VitePress](https://vitepress.dev/) for documentation
- [Vitest](https://vitest.dev/) for testing