diagramkit

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

Features

• Three diagram engines -- Mermaid, Excalidraw, and Draw.io, all rendered through a single headless Chromium instance
• 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) are an optional post-processing step via sharp
• Multiple output formats -- SVG, PNG, JPEG, and WebP with configurable scale and quality
• CLI and programmatic API -- use from scripts or import directly into Node.js projects

Install

npm install diagramkit

Install the Playwright Chromium binary (once per environment):

npx diagramkit warmup

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

npm install sharp

Quick start

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

diagramkit render architecture.mermaid

Render all diagrams in a directory:

diagramkit render .

Watch for changes and re-render automatically:

diagramkit render . --watch

Render to PNG for use in emails or Confluence:

diagramkit render . --format png --theme light

Render high-resolution WebP:

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

Filter by diagram type:

diagramkit render . --type mermaid

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

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=".diagrams/architecture-dark.svg" />
  <source media="(prefers-color-scheme: light)" srcset=".diagrams/architecture-light.svg" />
  <img alt="Architecture diagram" src=".diagrams/architecture-light.svg" />
</picture>

JavaScript API

import { render, renderFile, renderAll } 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 .diagrams/ folders)
await renderAll({ dir: './docs', format: 'svg', theme: 'both' })

Configuration

diagramkit loads configuration in layers: defaults, global (~/.config/diagramkit/config.json), local (.diagramkitrc.json, walking up the directory tree), and per-call overrides.

Create a .diagramkitrc.json in your project root:

{
  "outputDir": ".diagrams",
  "manifestFile": "diagrams.manifest.json",
  "useManifest": true,
  "sameFolder": false,
  "defaultFormat": "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 |

Documentation

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

Requirements

• Node.js >= 24
• Playwright Chromium (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

Validation scripts

# Lint and format check
npm run check

# Type checking
npm run typecheck

# Build library
npm run build

# Build docs site
npm run build:docs

# Unit tests (fast, no browser)
npm run test:unit

# E2E tests (requires Playwright Chromium + built dist)
npm run test:e2e

# Full validation (lint + typecheck + build + docs + unit + e2e)
npm run validate

See CONTRIBUTING.md for the full guide.

License

MIT