beautiful-mermaid

beautiful-mermaid is a TypeScript library that renders Mermaid diagram syntax — flowcharts, state diagrams, sequence diagrams, class diagrams, ER diagrams, and XY charts — into either self-contained SVG strings or ASCII/Unicode art for terminal output. It was built at Craft to power diagrams inside Craft Agents, replacing Mermaid’s default renderer with something faster, more themeable, and free of DOM dependencies.

Rendering is fully synchronous thanks to a FakeWorker bypass around the bundled ELK.js layout engine, so it drops straight into React’s useMemo() without async flicker. Theming is built on a two-color (bg/fg) CSS custom-property system with optional enrichment colors, 15 built-in themes, and full compatibility with Shiki/VS Code color themes via fromShikiTheme().

What You Get

• Two rendering back-ends — a synchronous SVG renderer for rich UIs and an ASCII/Unicode renderer for terminal output, generated from the same parsed diagram.
• A two-color theming system (bg/fg) that derives a full palette via CSS color-mix(), plus 15 built-in themes and direct Shiki/VS Code theme import.
• Synchronous rendering via a FakeWorker bypass around the bundled ELK.js layout engine, safe to call inside React’s useMemo() with no async flash.
• Support for six Mermaid diagram types: flowcharts, state diagrams, sequence diagrams, class diagrams, ER diagrams, and XY charts (bar, line, combined).
• Inline linkStyle support for per-edge stroke color and width overrides, matching Mermaid’s own linkStyle syntax.

Common Use Cases

• Rendering AI-generated Mermaid diagrams inline in a chat UI or coding assistant without a flash of unstyled content.
• Adding diagram support to a CLI tool or terminal-based coding agent via the ASCII/Unicode renderer.
• Matching diagrams to an app’s live theme by feeding CSS variables (var(—background), var(—foreground)) directly into the renderer.
• Importing a VS Code/Shiki theme so code blocks and diagrams share the exact same color palette.

Under The Hood

Architecture beautiful-mermaid is organized as one dedicated parser/layout/renderer pipeline per diagram type — the top-level parser.ts, layout.ts, and renderer.ts handle flowcharts and state diagrams, while sequence/, class/, er/, and xychart/ each carry their own parser.ts, layout.ts, and renderer.ts, plus a shared ascii/ tree (canvas.ts, draw.ts, edge-routing.ts, grid.ts, pathfinder.ts) that converts any positioned graph into terminal art. index.ts is a thin dispatcher: detectDiagramType() sniffs the first non-comment line and routes to the matching parser → layout function → render function chain, returning a plain string — there’s no shared mutable state or DOM, so swapping the layout engine would only touch the handful of layout.ts files that call it, not the parsers or renderers.

Tech Stack The library is pure TypeScript (strict mode, noUncheckedIndexedAccess) built with tsup for dual ESM output and bun as the primary dev/test runtime; runtime dependencies are minimal — elkjs for layered graph layout and entities for XML entity decoding — with shiki as an optional dev-time integration for VS Code theme import. A wrangler.toml and build:site script deploy a static demo/editor to Cloudflare Pages, but that tooling is separate from the published package, whose exports map (a bundled entry for consumers, source entry for Bun) keeps the public surface small.

Code Quality Test coverage is extensive — over twenty files under src/tests/ covering parser edge cases, layout integration, ASCII rendering, and per-diagram-type behavior — run via the test runner in CI alongside a separate type-check step. Error handling favors fast, descriptive throws (invalid mermaid headers, empty diagrams, layout failures) over try/catch suppression — there are essentially no catch blocks in the source tree, so failures surface immediately to the caller rather than being silently swallowed.

API Design The standout technical choice is the synchronous bypass of the underlying layout engine’s own async API: that engine normally wraps every layout call in a fake-worker abstraction that defers both message-send and message-receive through a zero-delay timer, but beautiful-mermaid captures those deferred callbacks during construction and dispatches directly, making the main render call genuinely synchronous and safe to call from React’s useMemo() with zero flash — a meaningfully different tradeoff than most diagram libraries, which are either async-only or ship their own from-scratch layout engine. The public API is deliberately small, documented with runnable examples in comments, and the two-color theming model with derived fallbacks means a caller can get a coherent themed diagram by supplying only two values.