Mermaid v13: going on a diet, and we want your input

[knsv]

Many of you have told us Mermaid has gotten heavy. The bundle is large, rendering is slower than it should be, server-side rendering needs a browser, and the security surface is bigger than a diagramming library should have.

The v13 alpha is a proof of concept of one answer: a full rewrite. The other path is gradual updates to v12. We haven't chosen yet, and this discussion will help us decide.

The proof of concept

• Diagram types, layouts and optional features are plugins, so you ship only what you use.
• It renders without a DOM: on the server, in workers and in a CLI, with no headless browser.
• It is much smaller and faster. Only 80 KiB for flowchart-only, 100x faster
• The syntax stays the same.

Try it with npm install mermaid@v13-alpha. It only renders flowcharts so far and isn't ready for production. Getting started with the v13 alpha has the details.

What we'd like to know

Start your reply by saying whether you write diagrams or embed Mermaid in a project, then answer any of these. One answer helps. If you'd rather click than write: [users poll] · [integrators poll]

1. Which diagram types and features do you actually use, and what would you move to an opt-in plugin to get a faster Mermaid? If you embed Mermaid, what is your bundle budget?
2. Without a DOM, v13 measures text from font metrics instead of asking the browser, so labels can come out slightly off. When a diagram looks bad, what is usually wrong? Would you accept slower rendering for a better layout? Do you use custom fonts, CJK, RTL or emoji?
3. CSS variables let diagrams switch between light and dark mode without re-rendering, but Inkscape, office apps and other SVG 1.1 tools ignore them. Which do you need? What is hardest to style today?
4. We want to replace HTML labels with Markdown (bold, italic, line breaks, links) rendered as plain SVG. HTML labels have to be measured in a real DOM, every diagram type needs a second label code path for them, and SVG renderers outside the browser break on them. What do you use HTML labels for, and would Markdown cover it? Would keeping them as an opt-in for backwards compatibility work better for you?

Taking part

• Try the alpha and report what breaks with the v13 alpha bug report.
• Answer the questions above in this thread. Use this link to reply

Mermaid is MIT-licensed. Many of its ideas came from issues, pull requests and discussions. Thank you to everyone who contributed. The company behind mermaid.ai (formerly Mermaid Chart) contributes engineering time to it, including much of the work on v13.

Thank you for building with Mermaid. 🧜‍♀️

[lex-gsynergy]

I use Mermaid in both ways here at GSynergy: I write diagrams and also (used to) embed Mermaid into our software.

I was very surprised to learn about the browser dependency of Mermaid when my Node unit tests started failing (https://github.com/orgs/mermaid-js/discussions/7085), and I switched to Graphviz when I learned about it. A browser has millions of lines of code in its transitive dependencies, and it's just not really designed to be a library. Using a browser as a library is not just slow, but it also introduces attack surface from a security perspective and means that the behavior of your software can change whenever the browser version gets updated.

We use Markdown all over the place and use Mermaid/Graphviz for embedding diagrams into it:

• Our own docs are often Markdown
• Our design docs, co-edited with Claude Code, are often in Markdown
• UIs in our software let you enter description fields as Markdown
• Output from tools is in Markdown and sometimes includes diagrams

We use GitHub and sometimes check these files in. With Graphviz, that means people have to install an optional browser extension in order to get the diagrams rendered as they browse.

Our needs for the diagrams are usually very modest, just basic nodes with labels that are connected by lines, preferably with auto-layout. For more complex situations, I'd love semi-manual control, e.g. putting things into rows/columns or designing diagrams with some kind of nesting construct.

Specific diagram types like "ER diagram" or "sequence diagram" are not very interesting in my world as far as I can think; they tend to not be quite right since everyone does them a little differently. I would get much more value if you beef up the general-purpose diagram modes compared to the specific types.

Thanks for looking into a browser-free option for Mermaid!

[filipsajdak]

I write diagrams and I embed Mermaid in documents, so both sets of questions apply.

What I use. C4 (c4-beta and the existing C4 syntax), BPMN and swimlane diagrams, flowcharts with the ELK layout, and the usual flowchart, state, sequence, ER and class diagrams. The alpha page says C4 is not ported yet, and I would rather have C4, BPMN and swimlane as opt-in plugins than lose them.

Layout. Layout quality matters most to me, and I would accept slower rendering for it. What usually looks wrong is routing: edges that overlap or run through a label or a title, arrowheads piled into one blob, and diagrams too wide for the page. For documents the size is the limit: a 9-step flowchart chain in LR is a 1704 by 88 px strip, which prints at about 4.3 pt in a 16 cm column. Folded into rows with ELK it is 672 by 306 px, about 10.8 pt. I measured both on a local build; the numbers are mine, not from the project.

Open v12 work. I have open v12 pull requests for these areas: C4 (22), BPMN (2), swimlane-beta layout (5) and ELK layout (6). They are indexed in #8713. The question for the maintainers, no rush: should series like these land in v12, be ported as v13 plugins later, or wait for the decision between the two paths? I will keep them current either way.

I have no numbers on bundle budget, fonts or HTML-label use, so I leave those questions to others.

[filipsajdak]

Porting our C4, BPMN and swimlane work to the v13 alpha as plugins found no blocker, but four gaps in the plugin contract.

All four ported plugins render in Node with no DOM on 13.0.0-alpha.1. I compared them with the v12 output of our open pull requests. The sources are legacy C4Context and friends (57), c4-beta (27), swimlane-beta (42 layout fixtures and 14 docs examples) and bpmn-beta (16 docs examples and a regression case). The code, a fit table per v12 dependency, and side-by-side notes are at https://github.com/filipsajdak/mermaid-v13-plugins. It is a community experiment, not affiliated with the Mermaid project.

What fit without trouble. Hand-written parsers on parser-kit replaced the jison, Langium and Chevrotain grammars. Boundaries map to LayoutGroup, shapes and arrowheads fit the SVG allow-list, and limits and accessibility fit. swimlane-beta reuses the flowchart package's exports, because in v12 it is the flowchart grammar with another layout.

Gaps in the contract (each is worked around in the repo, evidence in docs/FIT.md):

1. A plugin cannot add keys to a core config section or add theme variables. Our two converged C4 keys had to go through config aliases in a separate extension, and themeVariables.bpmn cannot be supported at all.
2. LayoutGraph has groups but no lanes, pools, bands or per-edge direction hints, and edges end on the box side, not on the shape outline. BPMN and swimlane therefore use layoutKind: 'custom' with the swimlane layout engine lifted from v12 (493 KB, no DOM and no dependencies).
3. Legacy types need registerExternalDiagrams(..., { replace: true }). Discovery skips a package with a first-party id, and DiagramPlugin.aliases is not read.
4. A theme paint requested after the root <svg> is written is never declared, so the browser draws black fills with no warning.

Bugs found on the way, filed with the v13 alpha template: #8714 (the c4 detector matches any text that contains C4Container, and a %% C4... comment now breaks flowcharts), #8715 (front-matter title not drawn), #8716 (ER markdown), #8717 (fontFamily: courier clips text in Node), #8718 (a plugin with a layout member fails to load lazily), #8719 (an ELK hang on a state transition to its own child) and #8720 (themeCSS ignored).

The open v12 pull requests stay current either way; they are indexed in #8713.

[knsv]

@filipsajdak Check your email