beautiful-mermaid

beautiful-mermaid is a TypeScript library for rendering Mermaid diagrams as clean SVG images or as ASCII art for terminals. Mermaid is a popular text-based format for writing diagrams in plain text, and this library provides an alternative renderer focused on visual quality and flexibility compared to the official Mermaid renderer.

The library was built by the team behind Craft, a note-taking and document tool, to power diagrams inside their AI agent product. The README describes motivations as: the default Mermaid renderer requires a browser DOM and can be slow, its theming involves CSS complexity, and it cannot render to text for command-line tools. This library addresses all three by running in pure TypeScript with no browser dependencies, supporting ASCII output alongside SVG, and using a simple two-color theming system.

The theming approach is one of the library's main features. You provide a background color and a foreground color, and the library derives all other diagram element colors automatically. For more control, you can supply additional optional colors for specific elements. Fifteen built-in themes are included, covering common editor and IDE color schemes like Tokyo Night, Catppuccin, Nord, Dracula, GitHub, Solarized, and One Dark. Themes can also be switched live using CSS custom properties without re-rendering.

Rendering is synchronous rather than asynchronous, which makes it straightforward to use inside React components with memoization, avoiding the flickering that can occur when diagram rendering happens in side effects. The library supports flowcharts, state diagrams, sequence diagrams, class diagrams, entity-relationship diagrams, and XY charts including bar and line charts.

The ASCII output uses Unicode box-drawing characters to produce terminal-friendly diagrams, adapted from an earlier Go project. The package is available on npm and works in any JavaScript environment.