diagramkit

Render .mermaid, .excalidraw, .drawio, and Graphviz .dot / .gv / .graphviz diagrams to SVG, PNG, JPEG, WebP, or AVIF from the command line or as a library -- with automatic light/dark mode and incremental builds.

Features

• Four diagram engines -- Mermaid, Excalidraw, Draw.io, and Graphviz. Browser-backed engines reuse a single headless Chromium instance, while Graphviz is rendered with bundled Viz.js/WASM
• Light and dark mode -- both theme variants are generated by default, with automatic WCAG contrast optimization for dark SVGs
• Incremental builds -- SHA-256 content hashing tracks source changes so unchanged diagrams are never re-rendered
• Watch mode -- file watcher triggers re-renders on save
• SVG-first pipeline -- core output is always SVG; raster formats (PNG, JPEG, WebP, AVIF) are an optional post-processing step via sharp
• Multiple output formats -- SVG, PNG, JPEG, WebP, and AVIF with configurable scale and quality
• CLI and programmatic API -- use from scripts or import directly into Node.js projects

Install

npm add diagramkit

Install the Playwright Chromium binary (once per environment):

npx diagramkit warmup

The CLI supports the common installed-package entrypoints:

npx diagramkit --version
./node_modules/.bin/diagramkit --version
node ./node_modules/diagramkit/dist/cli/bin.mjs --version

For raster output (PNG, JPEG, WebP, AVIF), also install sharp:

npm add sharp

Quick start

Render a single file (produces both light and dark SVGs):

npx diagramkit render architecture.mermaid

Render all diagrams in a directory:

npx diagramkit render .

Watch for changes and re-render automatically:

npx diagramkit render . --watch

Render to PNG for use in emails or Confluence:

npx diagramkit render . --format png --theme light

Render high-resolution WebP:

npx diagramkit render . --format webp --quality 85 --scale 3

Filter by diagram type:

npx diagramkit render . --type mermaid
npx diagramkit render . --type graphviz

Output files are placed in a .diagramkit/ folder next to each source file. Filenames include -light or -dark suffixes.

AI Agent Usage

diagramkit is designed for AI agent workflows. Every agent skill ships inside the npm package at node_modules/diagramkit/skills/, and the diagramkit-setup skill writes tiny local pointer SKILL.md files in your repo that defer to those bundled originals — so any agent (Claude Code, Cursor, Codex, Continue, OpenCode, ...) reads guidance pinned to the exact CLI version it is about to call.

Copy-paste agent prompt: install latest diagramkit + configure skills

Paste this into your AI coding agent. It does the three things you need in one shot: install the latest release, read the version-pinned reference, and configure the local-pointer skills.

Install the latest diagramkit in this repo and configure its agent skills:

1. npm add diagramkit@latest
   Confirm with: npx diagramkit --version

2. Read node_modules/diagramkit/REFERENCE.md end to end. It is the
   version-pinned CLI/API contract for the release you just installed.
   Do NOT rely on a globally installed diagramkit or on training data.

3. Follow node_modules/diagramkit/skills/diagramkit-setup/SKILL.md end to
   end. It will run `npx diagramkit warmup` (skip if Graphviz-only), wire
   a `render:diagrams` script into package.json, optionally create
   diagramkit.config.json5 (`npx diagramkit init --yes`), render any
   existing diagrams, and write thin pointer SKILL.md files at:
     .agents/skills/diagramkit-<name>/SKILL.md    (always)
     .claude/skills/diagramkit-<name>/SKILL.md    (if .claude/ exists)
     .cursor/skills/diagramkit-<name>/SKILL.md    (if .cursor/ exists)
     .codex/skills/diagramkit-<name>/SKILL.md     (if .codex/ exists)
     .continue/skills/diagramkit-<name>/SKILL.md  (if .continue/ exists)
   Each pointer defers to
   node_modules/diagramkit/skills/diagramkit-<name>/SKILL.md — so every
   `npm install diagramkit` upgrade automatically refreshes every skill.
   Skills installed: setup, auto, mermaid, excalidraw, draw-io, graphviz,
   review (validation + WCAG 2.2 AA contrast).

4. Commit the pointer SKILL.md files with any package.json / config
   changes. Summarize what was created or skipped.

Copy-paste agent prompt: generate a diagram and its image variants

Create a [TOPIC] diagram in this repo using the locally installed diagramkit
and the diagramkit-* skills. Read `node_modules/diagramkit/REFERENCE.md` first
so you use the version installed under `node_modules/`. Follow
`.agents/skills/diagramkit-auto/SKILL.md` (or your harness mirror under
`.claude/skills/`, `.cursor/skills/`, `.codex/skills/`) to pick the best
engine, then the matching engine skill (mermaid / excalidraw / draw-io /
graphviz). Save the source under `diagrams/`, render both light and dark
variants, and also export PNG + WebP for docs:
  npx diagramkit render diagrams/<file> --format svg,png,webp --scale 2
Embed it in the relevant markdown using the `<picture>` pattern.

Copy-paste agent prompt: validate every diagram (WCAG 2.2 AA contrast)

Audit every diagram in this repo for structural validity, `<img>`-embed
safety, and WCAG 2.2 AA text/background contrast. Read
`node_modules/diagramkit/REFERENCE.md` first, then follow
`.agents/skills/diagramkit-review/SKILL.md` (or
`node_modules/diagramkit/skills/diagramkit-review/SKILL.md` directly). It
will force-render every diagram, run `diagramkit validate . --recursive
--json`, classify issues into errors vs warnings, and delegate per-engine
fixes (palette swaps for `LOW_CONTRAST_TEXT`, `htmlLabels: false` for
foreignObject, etc.) back to the matching engine skill's "Review Mode".

How skills are installed

The recommended path is local pointers into node_modules/diagramkit/skills/, written by the diagramkit-setup skill. Each pointer is a tiny SKILL.md (frontmatter + a one-line "follow node_modules/diagramkit/skills/<name>/SKILL.md" instruction) committed at .agents/skills/diagramkit-<name>/SKILL.md (with mirrors under .claude/skills/, .cursor/skills/, .codex/skills/, .continue/skills/ for the harnesses the repo uses). Benefits:

• Version-pinned — the linked SKILL.md is the exact one bundled with the installed diagramkit, so agents never read guidance that's ahead of or behind the CLI they're calling.
• Zero extra dependency — the skills already ship in the npm package; no separate fetch step.
• Git-friendly — pointers are stable across upgrades; the linked content tracks the package.

The standalone skills CLI is also supported (npx skills add sujeet-pro/diagramkit) when you specifically want skills that update independently of the installed diagramkit. Pick one mechanism per repo so they don't drift.

Shipped agent skills

| Capability | Skill | | ---------------------------------------------------------------------------- | ----------------------- | | Bootstrap (install, warmup, config, scripts, skill pointers). Run first. | diagramkit-setup | | Engine routing for new diagram requests | diagramkit-auto | | Authoring + image generation (vector + raster) — Mermaid | diagramkit-mermaid | | Authoring + image generation (vector + raster) — Excalidraw | diagramkit-excalidraw | | Authoring + image generation (vector + raster) — Draw.io | diagramkit-draw-io | | Authoring + image generation (vector + raster) — Graphviz | diagramkit-graphviz | | Validation (SVG structure, <img>-embed safety) + WCAG 2.2 AA contrast | diagramkit-review |

All diagramkit-* skills always prefer the locally installed CLI: they read node_modules/diagramkit/REFERENCE.md first and run npx diagramkit ... (which auto-resolves to ./node_modules/.bin/diagramkit) so the agent never accidentally uses a different globally installed version.

Agent-facing files shipped in the package

| File | Use when | | ------------------------------------ | ------------------------------------------------------------------------------- | | REFERENCE.md | Single landing page — read first. | | llms.txt | You want practical CLI defaults and examples | | llms-full.txt | You need complete CLI + API reference | | ai-guidelines/usage.md | Primary agent setup instructions | | ai-guidelines/diagram-authoring.md | Per-engine authoring reference | | skills/diagramkit-*/SKILL.md | Skill source — installed into your repo as local pointers by diagramkit-setup |

After installation, the agent's first read should be node_modules/diagramkit/REFERENCE.md. Use diagramkit --agent-help when the agent needs the full reference in one stream.

See the Getting Started guide and the AI Agents guide for more prompt recipes.

Embedding light/dark SVGs in Markdown

Use a <picture> element so GitHub and other renderers pick the right variant based on the viewer's color scheme:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset=".diagramkit/architecture-dark.svg" />
  <source media="(prefers-color-scheme: light)" srcset=".diagramkit/architecture-light.svg" />
  <img alt="Architecture diagram" src=".diagramkit/architecture-light.svg" />
</picture>

JavaScript API

import { render, renderFile, renderAll, dispose } from 'diagramkit'

// Render from a string (returns in-memory RenderResult)
const result = await render('graph LR; A-->B', 'mermaid', {
  theme: 'both',
  format: 'svg',
})

// Render a single file (returns in-memory RenderResult, does NOT write to disk)
const fileResult = await renderFile('docs/architecture.mermaid')

// Batch render an entire directory (discovers files, writes output to .diagramkit/ folders)
const batchResult = await renderAll({ dir: './docs', formats: ['svg'], theme: 'both' })
await dispose()
console.log(batchResult.failedDetails)

For isolated workers or long-running services, use createRendererRuntime() and call runtime.dispose() when that runtime is done. The default top-level APIs share a singleton browser pool.

Import paths:

• diagramkit - core rendering APIs
• diagramkit/utils - discovery/manifest/output/validation helpers for custom pipelines
• diagramkit/color - dark SVG contrast utilities
• diagramkit/convert - SVG-to-raster conversion only
• diagramkit/validate - SVG structural + img-tag-compatibility checks

Configuration

diagramkit loads configuration in layers: defaults, global (~/.config/diagramkit/config.json5), env vars (DIAGRAMKIT_*), local (diagramkit.config.json5 or .ts, walking up the directory tree), and per-call overrides.

Create a config file with diagramkit init (JSON5) or diagramkit init --ts (TypeScript):

{
  // diagramkit.config.json5
  outputDir: '.diagramkit',
  defaultFormats: ['svg'],
  defaultTheme: 'both',
}

Supported extensions

| Extension | Diagram type | | ------------- | ------------ | | .mermaid | Mermaid | | .mmd | Mermaid | | .mmdc | Mermaid | | .excalidraw | Excalidraw | | .drawio | Draw.io | | .drawio.xml | Draw.io | | .dio | Draw.io | | .dot | Graphviz | | .gv | Graphviz | | .graphviz | Graphviz |

Documentation

Full documentation is available at projects.sujeet.pro/diagramkit.

Key guides:

• Architecture
• CI/CD Integration
• Troubleshooting

Requirements

• Node.js >= 24
• Playwright Chromium for Mermaid, Excalidraw, and Draw.io renders (installed via npx diagramkit warmup)
• sharp (optional, only needed for raster output)

Development

git clone https://github.com/sujeet-pro/diagramkit.git
cd diagramkit
npm install
npx playwright install chromium
npm run build

Tooling

diagramkit uses vite-plus as its unified development toolchain. A single vite.config.ts handles building (Rolldown), testing (Vitest), linting (Oxlint), and formatting (Oxfmt) — no separate config files needed.

All scripts use the vp CLI provided by vite-plus:

| Script | Command | Description | | ------------------- | ------------------------------------------- | ------------------------------------------------ | | npm run build | vp pack | Build the library with Rolldown | | npm run build:all | build:lib && build:docs | Build the library and the docs site | | npm run test | vp test run | Run all tests | | npm run test:unit | vp test run src/ | Unit tests (fast, no browser) | | npm run test:e2e | vp test run e2e/ | E2E tests (requires Playwright + built dist) | | npm run check | vp check | Lint (Oxlint) + format (Oxfmt) check | | npm run check:fix | vp check --fix | Auto-fix lint and format issues | | npm run typecheck | tsc --noEmit | TypeScript type checking | | npm run preview | build:all && preview:docs | Build everything then preview the docs site | | npm run cicd | check + typecheck + build:all + tests + val | Canonical pre-merge gate (also what CI runs) | | npm run validate | alias for cicd | Back-compat alias |

npm overrides

The overrides field in package.json exists because vite-plus repackages Vite and Vitest under its own scope (@voidzero-dev/vite-plus-core and @voidzero-dev/vite-plus-test). Transitive dependencies from packages like @excalidraw/excalidraw or mermaid that depend on vite or vitest are redirected to the vite-plus versions to avoid duplicate installs. The dompurify and nanoid overrides are security patches for transitive dependencies.

AI setup for docs workflows

Use the Pagesmith CLI (not the low-level API) to install AI artifacts without overwriting diagramkit's own llms.txt files:

npm run ai:init

This runs pagesmith init --ai --no-llms --yes --config ./pagesmith.config.json5.

See CONTRIBUTING.md for the full guide. Please read our Code of Conduct and Security Policy.

License

MIT