Mermaid 13 alpha: smaller, faster, and we haven't decided whether to ship it

• 6 mins

The Mermaid 13 alpha is a rewrite: a small core, about 50 times faster in early measurements, plain SVG, and no browser needed. We haven't decided how to ship it, and we'd like your help deciding.

I started Mermaid in 2014 to turn text like A --> B into a diagram. Today it renders inside GitHub, GitLab, and a long list of editors and wikis. Millions of documents depend on it drawing tomorrow what it drew yesterday.

The Mermaid 13 alpha is on npm. It is a rewrite, it is a proof of concept, and we haven’t decided whether to ship it this way. I’d like your help deciding.

What we heard

I’ve read the feedback on Mermaid closely this year. Most of it is fair, and some of it is overdue.

  • It’s big and slow. Drawing one flowchart means downloading over 200 KB of compressed JavaScript.
  • The SVG breaks outside the browser. Labels are embedded HTML, which falls apart in PDF tools, Inkscape, and anything else that expects plain SVG.
  • Rendering on a server needs a whole browser. To make an image in a build pipeline, you start headless Chrome.

Some teams that embed Mermaid stopped waiting and wrote their own renderers. That’s a clear signal.

Then we profiled v12 and found something nobody had complained about: over half of the render time went to copying configuration objects. That fix is going into v12 as well. But it showed how much cost had piled up where nobody looks, and that patching around the edges wasn’t enough.

What v13 is

A small core plus pieces you pick. Each diagram type is its own package. So are layout engines and extras such as icons, math, and a hand-drawn look.

  • Faster. About 50 times faster than v12 in early measurements.
  • Smaller. A flowchart takes about 130 KB instead of a little over 200. The core alone is under 100 KB.
  • No dependencies in the core. v12 pulls in 86 packages.
  • No browser needed. It runs in Node, Deno, and web workers.
  • Plain SVG. No embedded HTML, labels as ordinary text, and a stable ID on every node and edge.
  • Predictable. The same input gives the same SVG, byte for byte. Errors come with a code, line, and column.

If you just want Mermaid, nothing changes. This works the same in v12 and v13:

import mermaid from 'mermaid';

const { svg } = await mermaid.render('id', 'flowchart LR\n  A --> B');

If you want it small, pick the diagram types yourself:

import { createMermaid } from 'mermaid/slim';
import { flowchart } from '@mermaid-js/diagram-flowchart';

const mermaid = createMermaid({ diagrams: [flowchart] });

Third-party diagram types work the same way as ours. A community diagram is an npm package, not a pull request into the main repo.

Yes, it’s a rewrite, and AI agents wrote most of it

In 2000, Joel Spolsky called rewriting from scratch “the single worst strategic mistake that any software company can make.” Old code is full of fixes, a rewrite throws those lessons away, and you ship nothing while you rebuild.

I think he was right in 2000. I’m not sure he’s right now, and v13 is our experiment to find out. Two things have changed.

Time got cheap. The design had been on our roadmap for about a year. The first alpha was on npm less than a week after the first commit. Most of the building was done by AI coding agents, with people deciding what to build and reviewing what came back.

The knowledge doesn’t have to be thrown away. We brought over v12’s algorithms and wrote new code around them. And v12 itself is the test: every v13 parser is checked against what v12 accepts, across thousands of real diagrams. When the two disagree, v13 is wrong until shown otherwise.

The agents aren’t magic. Our retrospective is in the repo, and it lists what went wrong. Agents changed defaults without asking. Some reported work as finished when it wasn’t. The fix was process: every piece of work is reviewed before it merges, and any change to a default goes to a person.

Where Spolsky is still right is the part no test suite covers: what people rely on without writing it down. A CSS selector that reaches into our SVG. A tool that post-processes the HTML in our labels. Those are what a rewrite breaks, and they’re why we haven’t decided how to ship it.

What can break

Our rule is: syntax is sacred, pixels are not. Every diagram written for v12 should read the same in v13. If you find one that doesn’t, it’s a bug, and we want it.

Your diagrams will look somewhat different, with a new default theme and layout engine. What can actually break is code that depends on how Mermaid draws:

  • CSS that targets v12’s SVG structure may no longer match.
  • The htmlLabels setting is gone. Bold, italics, and line breaks in labels still work.
  • themeCSS is ignored. Theming goes through CSS variables.
  • Click handlers on nodes now come from a plugin.
  • The old mermaidAPI object is removed. render, parse, initialize, and run keep their signatures.
  • ZenUML isn’t supported.

The full list is in the migration guide.

The decision we haven’t made

  • Launch v13 as it is. Everything at once. The payoff is big and soon. The risk is that the breaks above hit everyone at the same moment.
  • Migrate gradually. Bring the same ideas into v12 piece by piece. Fewer surprises per release, and the gains arrive later.

I lean towards launching v13. Most of what people asked for only becomes possible with the new structure.

Two things would change my mind: strong feedback that the breaks hurt more than the gains help, or hearing that size and speed don’t matter much to you. Either way, v12 keeps getting fixes while v13 is in alpha and beta.

What won’t change

Mermaid stays MIT. So does everything in the open-source repo, the core and every plugin in it. The core will never be weakened to make room for a paid tier. Mermaid Chart builds its products on top of open Mermaid, the same way anyone else can.

Try it, and tell us

npm install mermaid@v13-alpha --save-exact

It’s an alpha: pin the exact version, and don’t put it in production yet. What we most need to hear:

  • Does it render your real diagrams correctly? Which ones don’t?
  • Do you style, select into, or post-process Mermaid’s SVG? How?
  • Do size and speed matter to you, or are they overblown?
  • Launch v13 as it is, or migrate gradually?

Tell us in the open discussion on GitHub. Thank you.

Knut


v13’s default layout engine builds on code from Pele, which is MIT licensed. Thank you.