Leadership1 publisher2 min readPublished
Mermaid 12.0 redraws the flowcharts and class diagrams teams have already published
Mermaid 12.0 re-lays out and recolours existing flowcharts, state and class diagrams by default, and requires ES2024 and Safari 17.4 or later. Three config settings restore the old look, but older browsers need a polyfill or transpile step.
The Board Room · Leadership desk
What happened
- ELK used to ship as a separate @mermaid-js/layout-elk package that sites had to install and register; 12.0 bundles it and registers it automatically.
- Flowchart, state, class, entity-relationship, requirement and use-case diagrams that do not name a layout are now laid out by ELK instead of dagre.
- The single-file mermaid.min.js build inlines ELK and grows by roughly 500 kB gzipped, while the ESM builds fetch ELK only when a diagram uses it.
- The defaultRenderer option is removed from the flowchart, class and state config sections in favour of the top-level layout setting.
Compiled by The Board RoomSomething wrong?How this is made
Why it matters
- constraint No config setting brings back support for older iOS devices, so sites with those readers must either add a polyfill or transpile step or hold on the previous major version.
- contradiction The release summary lists three affected diagram types, but the detailed notes also move entity-relationship and requirement diagrams to ELK, so a review scoped to the summary misses two.
- cost Sites on the single-file build carry the extra 500 kB or so even if every diagram is pinned to dagre, while ESM sites that pin never download ELK.
- decision Pinning the three old settings keeps published diagrams stable now and moves the ELK layout review into whichever later upgrade the team finally accepts it.
On a planning slide, the upgrade fits in one line. Set layout: dagre, theme: default and look: classic, and the old appearance returns, according to the release notes [3]. That line leaves out the browser requirement. The project calls 12.0 a breaking release [2]. Mermaid is now built to target ES2024 and Safari 17.4, and the notes say: "If you need to support older browsers, you may need to polyfill or transpile mermaid" [4]. The project gives its reason for the Safari floor: "unlike Firefox/Chrome, older iOS devices don't get major Safari updates" [5].
The Node.js 22.12 requirement affects a different set of machines. Mermaid needs a browser to render. The notes say the Node floor is declared mainly so the project can use dependencies with the same requirement without causing problems when users run npm install [6]. For a docs team, it matters wherever packages get installed [6].
Use case diagrams are new in 12.0 [1]. That means five of the diagram types the detailed notes move to ELK could already be in a team's docs [1]. Mindmaps keep their cose-bilkent layout [9].
Most of the packaging work is deletion. Existing mermaid.registerLayoutLoaders(elkLayouts) calls keep working and can be removed, and the separate @mermaid-js/layout-elk package is still the way to add ELK to the tiny build [17]. The tiny build omits ELK, keeps its size and falls back to dagre [11]. One path does break. Vite rejects syntax in dist/mermaid.esm.min.mjs, so builds pointed straight at that file have to switch to the mermaid package specifier or the core build [12].
Config files need their own check. The notes explain the removal of defaultRenderer plainly: "The option's documented purpose no longer existed" [14]. Every accepted value had come to select the same renderer, while an invalid value silently sent a diagram to the legacy renderer [15]. A related fix means an unrecognised theme name now resolves to the default theme in name as well as in its variables [16]. A site carrying a misspelled theme name will now get palette styling it previously skipped [3].
I think the three-setting pin is the sensible first step for a docs site with many published diagrams. It keeps what readers see stable while the team handles browser support as a separate project. Dagre is still in the 12.0 code, and the tiny build falls back to it [11]. The release notes do not say how long dagre will remain available as the alternative to ELK.
What to watch
- Any Mermaid release note that deprecates dagre or the classic look, turning the three-setting pin into a deadline.
- A 12.x point release addressing Vite's rejection of dist/mermaid.esm.min.mjs.
- Whether documentation platforms that bundle Mermaid move to 12.0 by default or hold their current version.