Add mermaid.tiny.min.js. 69.7% size reduction.

[sidharthv96]

📑 Summary

Adds a tiny version of mermaid that is optimized for the web. It is a subset of the mermaid library and is designed to be used in the browser via CDN.

<script src="https://cdn.jsdelivr.net/npm/@mermaid-js/tiny@11/dist/mermaid.tiny.js"></script>

Usage via NPM

This package is not meant to be installed directly from npm. It is designed to be used via CDN.
If you need to use mermaid in your project, please install the full mermaid package instead.

Removals from mermaid

This does not support

• Mindmap Diagram
• Architecture Diagram
• Katex rendering

Usage via CDN

Latest version

<script src="https://cdn.jsdelivr.net/npm/@mermaid-js/tiny/dist/mermaid.tiny.js"></script>

Specific version

<!-- Format -->
<script src="https://cdn.jsdelivr.net/npm/@mermaid-js/tiny@<MERMAID_MAJOR_VERSION>/dist/mermaid.tiny.js"></script>

<!-- Pinning major version -->
<script src="https://cdn.jsdelivr.net/npm/@mermaid-js/tiny@11/dist/mermaid.tiny.js"></script>

<!-- Pinning specific version -->
<script src="https://cdn.jsdelivr.net/npm/@mermaid-js/tiny@11.6.0/dist/mermaid.tiny.js"></script>

mermaid.min.js: 3mb
mermaid.tiny.min.js: 1.1mb

Resolves #4616

📏 Design Decisions

Uses the define feature of esbuild to exclude mindmap and flowchart-elk during build time.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines

[codecov]

Codecov Report

Attention: Patch coverage is 1.44928% with 68 lines in your changes missing coverage. Please review.

Project coverage is 3.87%. Comparing base (8c4fc3c) to head (c8daf9a).
Report is 209 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid/src/diagrams/common/common.ts	0.00%	26 Missing ⚠️
.esbuild/build.ts	0.00%	21 Missing ⚠️
.esbuild/util.ts	0.00%	12 Missing ⚠️
...s/mermaid/src/diagram-api/diagram-orchestration.ts	0.00%	4 Missing ⚠️
.vite/build.ts	0.00%	3 Missing ⚠️
packages/mermaid/src/diagrams/info/infoDb.ts	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #4734      +/-   ##
==========================================
- Coverage     3.87%   3.87%   -0.01%     
==========================================
  Files          412     413       +1     
  Lines        43134   43201      +67     
  Branches       664     666       +2     
==========================================
+ Hits          1672    1673       +1     
- Misses       41462   41528      +66     

Flag	Coverage Δ
unit	3.87% <1.44%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/mermaid/src/mermaidAPI.ts	0.30% <ø> (ø)
packages/mermaid/src/type.d.ts	100.00% <100.00%> (ø)
packages/mermaid/src/diagrams/info/infoDb.ts	14.28% <0.00%> (-2.39%)	⬇️
.vite/build.ts	0.87% <0.00%> (-0.03%)	⬇️
...s/mermaid/src/diagram-api/diagram-orchestration.ts	0.00% <0.00%> (ø)
.esbuild/util.ts	0.00% <0.00%> (ø)
.esbuild/build.ts	0.00% <0.00%> (ø)
packages/mermaid/src/diagrams/common/common.ts	31.87% <0.00%> (-0.72%)	⬇️

... and 13 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sidharthv96]

The version will be shown in error and info diagrams.

[aloisklink]

Nice! That's a massive size reduction!

I'm really against putting this in the mermaid package, because it will make the package bigger for everybody, even if they don't use the mermaid.tiny.min.js file, and it will add another file that we will never be able to get rid of without breaking backwards compatibility with CDNs.

I think this must go in a new package, maybe something like @mermaid-js/mermaid-tiny?

---

Two other recommendations that would be nice to fix, but not required:

• Instead of changing src/diagrams/.../detector.ts, can't we just prevent adding mindmap and flowchart/elk in the the diagram-orchestration.ts file, e.g. modifying these lines of code:

  mermaid/packages/mermaid/src/diagram-api/diagram-orchestration.ts

  Lines 74 to 77 in 5f95a26

  	flowchartElk,
  	flowchartV2,
  	flowchart,
  	mindmap,

  If ESBuild is smart enough, it should do tree shaking automatically, and it will have the same effect.

• I think the error diagram needs a more human readable message in case somebody does try to use mindmap or flowchart-elk with mermaid-tiny. We have to assume that users might not even know they're using mermaid-tiny, e.g. if they're using a third-party Mermaid plugin.

[sidharthv96]

I'm really against putting this in the mermaid package, because it will make the package bigger for everybody, even if they don't use the mermaid.tiny.min.js file.

The current unpacked size is 21MB, adding an extra 1MB to it is worth the tradeoff for not having to maintain and release another package. Moreover, this will only affect people using package managers, not actual end users.
Also, the compressed size increase would be few hundred KBs, which is negligible for our usecase.

Version	Size	Compressed
8.0.0	17.7 MB	3.4 MB
9.0.0	23.8 MB	5 MB
10.0.0	32.9 MB	6.5 MB
10.3.1	21.3 MB	4.5 MB
11.0.0-alpha.4	14.7 MB	4.2 MB

It will add another file that we will never be able to get rid of without breaking backwards compatibility with CDNs.

Now it's just a file, if we use a package, we'll have to maintain that in sync with mermaid, which is a bigger headache than having a file in the package with 0 active maintenance requirement.

[sidharthv96]

Instead of changing src/diagrams/.../detector.ts, can't we just prevent adding mindmap and flowchart/elk in the the diagram-orchestration.ts file, e.g. modifying these lines of code:

I tried that first, the file size didn't change. But I was using a different approach then (not define). Let me try now.

--

It worked! ❤️
This simplifies it a lot.

[sidharthv96]

I think the error diagram needs a more human readable message in case somebody does try to use mindmap or flowchart-elk with mermaid-tiny. We have to assume that users might not even know they're using mermaid-tiny, e.g. if they're using a third-party Mermaid plugin.

That would be out of scope for this PR. I did try a POC, but the changes will be extensive.

Especially since we're not even registering the diagrams since 55266c4

[aloisklink]

It will add another file that we will never be able to get rid of without breaking backwards compatibility with CDNs.

Now it's just a file, if we use a package, we'll have to maintain that in sync with mermaid, which is a bigger headache than having a file in the package with 0 active maintenance requirement.

I still don't agree with adding the mermaid.tiny.min.js file to the mermaid NPM package. It is something we might be stuck with forever, so I think it will actually add maintenance overhead. (I'm a bit worried that if Mermaid is still around 100 years in the future, this mermaid.tiny.min.js file will still be there, and we won't be able to get rid of it).

Would uploading this as a GitHub Release asset be a better idea (e.g. using something like https://docs.github.com/en/rest/releases/assets?apiVersion=2022-11-28)? This should be pretty easy to do (we just need to add another job in https://github.com/mermaid-js/mermaid/blob/develop/.github/workflows/release-publish.yml). Since GitHub Releases don't have an @latest feature, we'd then be safe to remove it/change it if we ever want to.

Regardless of what we pick, since adding another entry-point to mermaid is a pretty major change, we should get @knsv's approval first (maybe also other mermaid maintainers?).

I think long-term, having it in a separate NPM package like @mermaid-js/mermaid-tiny would be the cleanest way of doing things, but you're right, there's no point in doing that now until we fully migrate the mermaid repo into a mono-repo, with automated releases/changelogs for each individual package.

---

That would be out of scope for this PR. I did try a POC, but the changes will be extensive.

That's fair! It would be a nice feature to have, especially if custom Mermaid plugins become more popular (although since it's not a breaking change, that would be a feature that can go directly into the develop branch!)

[sidharthv96]

Would uploading this as a GitHub Release asset be a better idea (e.g. using something like https://docs.github.com/en/rest/releases/assets?apiVersion=2022-11-28)? This should be pretty easy to do (we just need to add another job in https://github.com/mermaid-js/mermaid/blob/develop/.github/workflows/release-publish.yml). Since GitHub Releases don't have an @latest feature, we'd then be safe to remove it/change it if we ever want to.

This could be a stop-gap measure till we have automated builds and separate packages.

Also, I don't think the @latest would be a major issue for us, as we have replaced the documentation with the correct major version number. So only people who go out of their way to use @latest against the official documentation would be affected when/if we remove the file from a later version of mermaid. As long as we keep it in v11, it should be good.

[sidharthv96]

I have this idea for fully customizable mermaid that people can download, containing code for only the diagrams that they need, in a single bundle, without lazy loading.

A browser based version could be done using esbuild-wasm, once the bundling in browser part is figured out.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Apr 24, 2025, 7:41 AM

[sidharthv96]

I've published @mermaid-js/tiny, so now users can use

<script src="https://cdn.jsdelivr.net/npm/@mermaid-js/tiny@11/dist/mermaid.tiny.js"></script>