Mermaid

Mermaid is a markdown based diagramming tool. It is a javascript library that can be used to generate diagrams from text, similar to Markdown.

I’ve been a maintainer of the mermaid project for a while now. Mostly focused on the live editor, mermaid.live .

Let’s see how far we can shrink mermaid from its current 2.05 MiB size.

Types of bundles in Mermaid

Standalone bundle - mermaid.js

This is usually imported directly by static sites via a script tag, and contains all dependencies required to render mermaid diagrams inside it. This is the largest bundle, with 0 external dependencies.

mermaid.esm.mjs is the ESM version of mermaid, which is the recommended version to use in modern browsers.

mermaid.min.js and mermaid.esm.min.mjs are minified versions of these bundles.

Mermaid Core bundle - mermaid.core.mjs

This contains only the core mermaid code and is supposed to be used with bundlers like Vite/Webpack/etc when including mermaid as a dependency in another project. There is no minified build as it is expected that the bundler will minify the code.

Package sizes

Composition of bundles

Now we need to know what each bundle contains and how they are composed. Only then can we figure out how we can reduce the bundle size.

A quick google search landed me on rollup-plugin-visualizer , which is a rollup plugin that generates a visual representation of the bundle.

This PR adds the visualizer plugin to the mermaid repo and generates 3 types of graphs.

Treemap & Sunburst are useful to see the space utilization. Network shows us the dependency graph. It’s a bit messy, so you might need to play around with the regex to clean some stuff out.

Opening the diagrams in new tab will give a better view.

mermaid.js

mermaid.core.mjs

You can see that the core build contains just the core internal components. (There are some extra dependencies added, I’m not really sure why vite included it, but it’s a very small fraction (7.8%), compared to 58.8% of unified build)

Shrinking the bundle

Lodash

Lodash is a very popular utility library, and is used by mermaid to perform some operations. It is a very large library, and is used in a very small fraction of the codebase.

We could replace it with custom code, but it might not help much as lodash is already a sub-dependency of dagreand dagre-d3.

But is there something easier?

The tree-map tells us that it is ~28% of our bundle size. That’s huge for something that’s only used in 2 places & 3 test files.

Turns out, yes.

The network graph shows that the biggest lodash mport is from mermaidAPI.ts.

And when looking at the import, it’s

import { isEmpty } from "lodash";

Whereas everywhere else, it’s

import memoize from "lodash/memoize";

So, let’s try changing that import.

- import { isEmpty } from "lodash";
+ import isEmpty from "lodash/isEmpty";

Build… And… Voilà!

And we can see that it has reduced the bundle size by 9.9% (214.48 KiB) for the ESM build, and 9.88% (225.44 KiB) for the UMD build. There is no change in core build, as it doesn’t contain any external dependencies.

The gzip and minified size changes are inline with the bundle size changes, so I won’t be showing them for the rest of the post. The ESM and UMD bundle size changes are also inline with each other, so I’ll only be showing the mermaid.js bundle size changes.

So just one line change reduced the bundle size by 9.88% (225.44 KiB). Awesome!

I tried using the lodash-es package, which is a ES module version of lodash, but it didn’t help much. It actually increased the size of the bundle by 30 KiB. So let’s stick with the lodash package.

But, if we were using the old import { isEmpty } from "lodash-es"; syntax, it would have reduced the bundle size without us having to change all imports to lodash/isEmpty, etc.

The sunburst diagram is a great tool to see which are the biggest components of the bundle. We can see that lodash s now 10.08% of the bundle size, and is still the biggest dependency.

Dagre & Dagre-D3

As these libraries were unmaintained, Alois Klink raised this PR to replace them with dagre-d3-es , which shaved off another 216KiB from the mermaid.js bundle.

But there’s something interesting here, the core build has gone up 21% in size. Let’s dig in.

So we can see that the savings came from unused stuff in dagre-d3 being tree shaken off, but a humongous lodash-es dependency was added. lodash-es was supposed to be tree-shakeable and the solution to the problem, but it seems like it’s not. So let’s try to fix it.

Looking at the source, we see the following import.

import _ from "lodash-es";

From a blog I read earlier (don’t remember which), I knew that this was a bad practice, and that we should import the specific functions we need, instead of the whole library. Or, we should do the following to enable tree-shaking.

import * as _ from "lodash-es";

As it’s an external dependency, we’ll have to raise a PR in the dagre-d3-es repo. But to validate the fix, we have to

• Fork it
• Build locally
• Link the local build it in pnpm
• Link it to mermaid
• Build mermaid

Or…

• Do a find & replace in node_modules > dagre-d3-es
• Build mermaid

- import _ from 'lodash-es';
+ import * as _ from 'lodash-es';

Guess which one I did? 😅

So, just by changing the import syntax, the bundle size shrank 7.88% (145 KiB).

I raised a PR in the dagre-es repo, and it was merged.

But the core is still up by 9.11%. What could it be?

Hmm… lodash and lodash-es… 🤔 Remember when I said lodash is a sub-dependency, well if you look at the packages, dagre & dagre-d3 were the ones importing lodash. Now that they’re gone, lodash is a direct, unnecessary dependency of mermaid. Let’s replace it with lodash-es, what dagre-d3-es is using.

So, core went from +9.11% to +2.36%. But mermaid.js went from -17.58% to -16.94%. What’s going on?

There is still 2 lodash! Ughh…

The network graph is supposed to be used to find dependencies, but I wasn’t able to find who is importing lodash. So I just randomly moved the cursor inside lodash to see if there’s any “imported by” that shows up. And there was!

Alois did mention in a comment that dagre-d3-es has a graphlib implementation. So let’s see if we can use that.

- import graphlib from 'graphlib';
+ import * as graphlib from 'dagre-d3-es/src/graphlib';
+ import * as graphlibJson from 'dagre-d3-es/src/graphlib/json';

...

- graphlib.json.write(graph);
+ graphlibJson.write(graph);

After making the above changes, we can see that the bundle size has gone down again by 8.4% (144 KiB). core is still up 2%, not great, not terrible.

Trimming mermaid.core.mjs

There were some external dependencies being added in mermaid.core.mjs, which was confusing as the core build is supposed to be free of external dependencies. Alois figured out why and even had a solution for it.

It looks like the issue we have is that vite is ignoring all of our dependencies for the mermaid.core.* builds, but it’s not ignoring the dependencies of our dependencies. This could be fixed with something like https://www.npmjs.com/package/rollup-plugin-node-externals maybe (I think rollup plugins usually work in Vite at least)

– Alois

Unfortunately, this plugin wasn’t working with vite. Digging into the source, I got the regex they were using to filter stuff out. Adding it directly into the build script worked.

-    external.push(...Object.keys(dependencies));
+    external.push(new RegExp('^(?:' + Object.keys(dependencies).join('|') + ')(?:/.+)?$'));

Finally, core is clean!

Conclusion

So, we started with a 2.28 MiB bundle, and ended up with a 1.56 MiB bundle. That’s a 31.48% reduction in bundle size. Not bad for a day’s work.

The load time difference on 4G connection preset.

I’ll cover how we added lazy loading to mermaid to further reduce the bundle size in a future post.

Special thanks to Alois , Thibaut (Teebo) , Denis Bardadym and all the creators of the tools used in this post.