mmdsvg

render mermaid flowcharts to svg. no browser, no puppeteer, no chromium.

npm i mmdsvg

why

to turn a mermaid diagram into an svg today you install @mermaid-js/mermaid-cli, which pulls puppeteer, which needs a whole copy of chromium. measured on macos arm64, july 2026:

npm i @mermaid-js/mermaid-cli   ->  423 MB of node_modules
mmdc -i x.mmd -o x.svg          ->  Error: Could not find chrome-headless-shell
                                    (ver. 150.0.7871.24)

that is not a broken install. after 423 MB it still cannot draw anything until you fetch a browser separately, which is another ~340 MB. all of it then has to live in your ci image, your docker layer and your lambda bundle. it is the reason "just render the diagrams in ci" quietly never happens.

this package is 50 kB, has zero dependencies and is one function call.

import { render } from 'mmdsvg'

const svg = render(`
flowchart TD
  A[Start] --> B{Is it working?}
  B -->|yes| C[Ship it]
  B -- no --> D[(Check logs)]
  D -.-> E((Fix))
  E ==> B
`)

cli

mmdsvg diagram.mmd -o diagram.svg
cat diagram.mmd | mmdsvg > out.svg
mmdsvg diagram.mmd --theme dark -o dark.svg

exits 1 with the line number when the source is wrong, so it drops into ci as one step.

what it understands

directions — TD / TB, BT, LR, RL

shapes

| syntax | shape | |---|---| | A[text] | rectangle | | A(text) | rounded | | A([text]) | stadium | | A[[text]] | subroutine | | A[(text)] | cylinder | | A((text)) | circle | | A{text} | rhombus | | A{{text}} | hexagon | | A[/text/] A[\text\] | parallelogram | | A>text] | asymmetric |

edges — --> --- -.-> -.- ==> === --x --o <-->, with labels written either -->|like this| or -- like this -->. long arrows (---->) push the ranks further apart, the same as mermaid.

also — chains (A --> B --> C), fan out (A & B --> C & D), subgraphs, %% comments, semicolons, quoted labels, self loops, and cycles. classDef, class, style, linkStyle and click are parsed and ignored so real world files still render.

layout

it does the proper thing rather than a grid: cycles are broken, nodes are ranked by longest path, long edges get invisible waypoints so they can bend, and then crossings are cut with the median heuristic plus adjacent swaps. coordinates are relaxed toward the median of each node's neighbours.

text is measured with real helvetica advance widths. without a browser nothing can measure a string for you, and guessing is why home made renderers produce boxes that do not fit their labels.

theming

render(src, { theme: 'dark' })
render(src, { theme: myPalette })          // your own colours
render(src, { layout: { rankGap: 80 } })   // your own spacing

or stop after layout and draw it yourself:

import { renderToDiagram } from 'mmdsvg'
const { nodes, edges, groups, width, height } = renderToDiagram(src)

what it does not do

flowcharts only. sequence, class, state, gantt, pie and the rest are not implemented — if you need those, mermaid itself is the answer.

output is svg. no png, because that needs a rasteriser and this package deliberately has no dependencies. pipe it through resvg or rsvg-convert if you need pixels.

correctness

51 tests. the svg is checked with a real xml parser, not a substring match, and labels are escaped so markup in a diagram cannot break out of the document. layout is asserted structurally — nodes on a rank never overlap, nothing lands outside the canvas, subgraph boxes actually contain their members, edges meet node borders, and TD comes out taller than it is wide while LR comes out wider than it is tall.

license

MIT