@rakudeji/dia

dia is a TSX-first Diagram as Code CLI for humans and LLMs. It turns reusable TSX into deterministic SVG without requiring authors to manage coordinates. JSON Model, View, Style, and Direct documents remain supported for interchange, generation, and compatibility.

The current V8 preview requires Node.js 22.12 or newer.

Render one TSX file

No project, package installation, or tsconfig.json is required for a one-off diagram. Create scratch.dia.tsx, import the authoring API from @rakudeji/dia, and run:

pnpm dlx @rakudeji/dia@latest render scratch.dia.tsx

This writes scratch.svg beside the source. The temporary CLI resolves the @rakudeji/dia import itself. Initialize a project only when diagrams need shared modules, third-party packages, or separate TypeScript checking.

Start a project

pnpm dlx @rakudeji/dia@latest init my-diagram
cd my-diagram
pnpm install
pnpm check
pnpm render

Use init . to initialize the current directory instead. Existing unrelated files are preserved, while template file conflicts fail with INIT_FILE_EXISTS and are never overwritten.

The generated project installs @rakudeji/dia locally. A global CLI installation is not required. It is a multi-diagram project: each diagrams/*.dia.tsx file is one entry, while components, View, and Style can be shared.

pnpm exec dia list
pnpm exec dia add request-flow
pnpm exec dia render request-flow
pnpm exec dia render --all
pnpm exec dia check --all
pnpm exec dia lint --all
pnpm exec dia export model --all

Named entries are declared in package.json#dia.diagrams. dia.default selects the entry used when no name is supplied, and dia.outDir receives <name>.svg and <name>.model.json artifacts.

Existing project

pnpm add -D @rakudeji/dia@latest
pnpm exec dia check model.json
pnpm exec dia render model.json -o diagram.svg
pnpm exec dia render model.json --format png -o diagram.png
pnpm exec dia render model.json --geometry geometry.json
pnpm exec dia render model.json --explain relaxed.svg

--explain writes the drawing a relaxed declaration would give when a contract is refused. dia already computes it — the prose names the statement to drop and the picture marks where the statements disagree — and it reached HTTP, MCP and the console before it reached a terminal, which is where the person reading it sits.

The command tree and generated help use citty. Rendering is always explicit: use dia render file.dia.tsx or dia render file.json; the old dia file shorthand is not accepted.

TSX projects import the authoring API from the same package:

import { defineDiagram } from "@rakudeji/dia";

export default defineDiagram({
  model: {
    entities: [
      { id: "client", type: "actor", properties: { label: "Client" } },
      { id: "api", type: "service", properties: { label: "API" } },
    ],
    relations: [{ type: "flow", from: "client", to: "api" }],
  },
});

Public TSX API

The package root intentionally exposes only the authoring surface, which is eight names: View, EntityRule, RelationRule, Constrain, defineDiagram, defineView, defineStyle, and defineModel.

A Model is facts, and facts are data: it is a plain { entities, relations } object, never JSX. JSX is for the View. tests/authoring-surface.test.mjs holds the list, and each name has to say there what it is for.

defineDiagram, defineView, and defineStyle return the opaque types DiagramDefinition, ViewDefinition, and StyleDefinition. Internal Artifact, Scene, layout, routing, and renderer types are not package-root APIs.

JSON Direct authoring remains supported with an explicit { "kind": "direct", "version": 1, ... } root. The unreleased version 0 form is not accepted.

dia uses Vite 8, Rolldown, and Oxc to evaluate trusted local TSX. Type checking remains an explicit project command and uses TypeScript 7.