Headless Mermaid rendering via TypeScript porting

The Pitch

Beautiful-mermaid is a zero-dependency TypeScript library released in January 2026 by Luki Labs to handle Mermaid syntax without a DOM. It provides a bridge for terminal-based UIs and AI-assisted development by outputting both professional SVGs and high-fidelity ASCII art (source: GitHub).

Under the Hood

The project is a direct TypeScript port and expansion of Alexander Grooff’s 'mermaid-ascii' Go implementation (source: GitHub README). By moving away from Go, the library allows for easier integration into Node.js backend environments and LLM-centric workflows that require text-based visualisations.

The renderer currently supports five specific diagram types: Flowcharts, State, Sequence, Class, and ER diagrams (source: Ecosystem Startup). Notably, the developers have extended the original ASCII engine to include support for Sequence and Class diagrams, which were not present in the original Go source (source: GitHub commit 2026).

Integration with modern developer environments is handled through 15 built-in themes that maintain full compatibility with Shiki and VS Code theme specifications (source: Project Docs). This allows for visual consistency across documentation and terminal interfaces without manual CSS overrides.

However, the transition from Go to TypeScript has introduced specific regressions. Early adopters have identified rendering bugs within the stateDiagram-v2 syntax, specifically where start and end nodes fail to render correctly in the output (source: HN Comment).

We don't know yet if the library will support the broader Mermaid 2026 syntax features, such as quadrant charts or mindmaps. There is also no public information regarding a long-term maintenance plan, as the tool appears to be a specialised utility developed for 'Craft Agents' (source: UsedBy Dossier).

Marcus's Take

Beautiful-mermaid is a pragmatic choice for backend engineers who need to generate diagrams inside CLI tools or LLM prompts without the overhead of Puppeteer or a browser. It is a functional tool for most standard diagrams, though the current state diagram bugs make it a bit like a compass that omits North. Use it for automated terminal reporting, but keep it out of your critical documentation pipeline until the stateDiagram-v2 rendering issues are resolved.

Ship clean code,
Marcus.