SebastianJS

SebastianJS is a mermaid wrapper designed to make it able to perform server-side svg renderers without needing a headless browser.

Sebastian 🦀 is the little mermaid 🧜‍♀️ buttler/friend/assistant. And it's a catchy name so be it sebastianJS.

Initial use case

I was tired of needing to use a headless browser in order to render mermaid diagrams. I tried different ways including mermaidjs-cli that still requires puppeter and a headless browser.

Browsing some of mermaidjs requests I found some that are demanding exactly this. So this is an attempt at fixing a problem not a lot of people have.

Goal

Use default mermaidjs implementation, this is not a fork. It is designed to remain a wrapper.

Focus is made on implementing SVG exports.

As this doesn't require a headless browser, it should be faster to render.

Installation

npm install sebastianjs

Usage

API

import { render } from 'sebastianjs';

const def = `graph TD; A[Start] --> B{OK?}; B -- Yes --> C[Done]; B -- No --> A;`;

const svg = await render(def, {
  theme: 'dark',
  themeVariables: { primaryColor: '#3366ff' },
  themeCSS: '.node rect{ rx:4; ry:4 }',
  width: 800,        // optional (defaults to 800)
  height: 600,       // optional (defaults to 600)
});

// svg is a <svg …> string

CLI

# From a file
sebastianjs input.mmd -o output.svg

# From stdin
echo 'graph TD; A-->B' | sebastianjs - > out.svg

# With theme options
sebastianjs input.mmd -o output.svg -t dark \
  --theme-vars '{"primaryColor":"#3366ff"}' \
  --theme-css '.node rect{rx:4;ry:4}'

# Set explicit width / height (influences layout + final svg size)
sebastianjs input.mmd -o out.svg -W 1200 -H 700

Demos

Prebuilt comparison demos are located in the github pages: https://creadri.github.io/sebastianjs/

npm run fetch:samples
npm run build:site
npm run benchmark

# Optional: Run deviation comparison tests (requires mermaid-cli in PATH)
DEVIATION_TESTS=1 npm test -- __tests__/samples-deviation.test.js --runInBand

# Run deviation on a single sample
# Using env var (matches by basename or relative path under samples folder):
DEVIATION_TESTS=1 DEVIATION_SAMPLE=flowchart__1.mmd npm test -- __tests__/samples-deviation.test.js --runInBand

# Direct CLI for ad-hoc runs:
node scripts/deviation-suite.mjs -f samples/mermaid-demos/flowchart__1.mmd

Roadmap

• Make structure of render method
• Implement tests for all known mermaidjs diagrams (excluding beta ones)
• Make first render implementation with minimal DOM support for basic flowchart
• Make a tiny CLI
• Mermaid theme support
• Fix positioning and sizing issues
• Release First viable option
• Analyze the feasability of PNG/GIF/JPEG exports and if reasonable implement it
• Create a benchmark to assess the difference in performance compared to mermaid-cli

Limitations

Note on accuracy : SebastianJS requires node-canvas for accurate, browserless text measurement (no headless browser).

Dependencies

Install dependencies for Canvas (Ubuntu/Debian)

sudo apt-get install -y build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

Src: https://www.npmjs.com/package/canvas

Licence

MIT License

Demo files where taken from mermaid-js/mermaid repository : Mermaid MIT License

Benchmark

Last updated: 2025-09-25T12:26:58.647Z

Rendering all sample diagrams (count: 228).

Summary Table

Metric	sebastianjs	mermaid-cli
Samples	228	228
Successful	199	224
Avg ms	84.81	1960.71
Total ms	19336.00	447043.00
Min ms	8.00	1750.00
Max ms	1325.00	2659.00

Mermaid Graph

xychart
  title "Average Render Time (ms)"
  x-axis [sebastianjs, mermaid-cli]
  bar [84.81, 1960.71]

Loading