isomorphic-mermaid

Mermaid with a pre-configured, server-friendly DOM so you can render diagrams in Node.js without reaching for a browser. Under the hood it wires up svgdom, jsdom, and dompurify so the Mermaid API works the same in server and client contexts.

Why this exists: render Mermaid in Node.js without Puppeteer, Playwright, or any headless browser dependencies—just pure JS with a lightweight DOM.

Install

npm install isomorphic-mermaid

Usage

// ESM only
import mermaid from "isomorphic-mermaid";

// Optionally override the default safe defaults
mermaid.initialize({
  startOnLoad: false,
  securityLevel: "strict",
  htmlLabels: false,
});

const { svg } = await mermaid.render("diagram-id", "graph TD; A-->B;");
console.log(svg); // => <svg ...>...</svg>

Notes:

• initialize is pre-wired with startOnLoad: false, htmlLabels: false, and securityLevel: "strict" to avoid unsafe HTML while rendering headlessly.
• A lightweight window/document is provided via svgdom, so you do not need to set any globals yourself.

Scripts

• npm test — run the node test suite.
• npm run build — type-check and emit ESM to dist/.
• npm run typecheck — TypeScript no-emit check.

Development

The code lives in src/main.ts and exports Mermaid with the injected DOM + the customized initialize. Tests in test/main_test.ts demonstrate rendering to SVG in a Node environment.

Acknowledgement

This package builds on the approach discussed in https://github.com/mermaid-js/mermaid/issues/6634.