Mermaid Modernisation Proposal

[sidharthv96]

As an 8-year-old project (wow!), Mermaid is starting to show its age, as some of our core dependencies have fallen behind.

This proposal is aimed at giving mermaid a fresh breath of air (water?), by replacing the deprecated components with their modern counterparts, whilst maintaining backward compatibility as much as possible.

Based on the activity chart, we're going stronger than ever before, thanks to the involvement of the founder @knsv, maintainers and our awesome community. We also passed 50k stars on GitHub 🤩.

There have been some notable PRs recently that has helped with modernization.

• Making a monorepo #3531 + Lazy Load
• Introducing TypeScript #3336
• Improved New Documentation  #3678
• Build mermaid using Vite #3503 and Vitest #3427

And some are already in the works to replace deprecated components.

• Replace dagre/dagre-d3 with dagre-d3-es #3809
• feat: Add chevrotain parser with Unicode support! #3432

#2456 was pivotal in listing many issues and getting most of them resolved.

We have been getting wonderful feature requests and ideas, and some are held back due to lack of support in underlying libraries. So here is the list of main change we have to make, with some pros & cons.

Note
This is not inteded to tarnish any of these projects or it's maintainers. Mermaid wouldn't have been mermaid had it not for been each and every single one of these libraries and maintainers.
Open source is always a voluntary commitment, no one is obliged to maintain anything unless they want to. We acknoledge and appreciate that fact wholehearteadly.
At the same time, we don't wan't to expose our users to security vulnerabilites and bugs, so we have to evolve.

Note
I'm aware that commit graphs do not indicate the quality of a project, but it shows whether it is actively maintained or not.
With the velocity of JS ecosystem, only very few niche projects can stay "alive" without active maintenance. 😞

jison

Issues

• Upgrade to newer jison repo #873
• Unicode character set not supported? #3213
• Doesn't work when arabic diacritics are present #3047

Possible alternatives

• Chevrotain

The new parser has a compatability layer to act as a drop in replacement for the existing JISON parser. So no changes in mermaid code will be required outside of the corresponding diagram's folder.

• Unicode support - Emojis!!
• Completely typed code
• Easy to debug
• Friendly logic, written in TS
• Faster - https://chevrotain.io/performance/
• ESM support
• No need of the loader headache

• Peg.js
• Ohm

Good read: https://tomassetti.me/parsing-in-javascript/

Impact to end users

Any parser that we use should have 100% backward compatibility, so nothing should change for end users who create diagrams/integrate into their projects.
They'll get full Unicode support with Emojis.

Impact to Maintainers & Developers

Will have to transform existing Jison grammar into new format, ensuring compatibility.
Will get Typescript support if using Chevrotain, but the grammar is more verbose than JISON. Good for debugging and new devs, bad for writing if already familiar with jison.

Dagre

Multiple layout issues reported.

Alternative - https://js.cytoscape.org/

Impact to end users

Diagrams may look different as layout algorithm changes - There is dagre inside cytoscape incase they want to retail old look.
Will have support to easily select new algorithms that cytoscape supports.
Will have features like pan & zoom built in.
Direct export support
Headless rendering might be possible

Impact to Maintainers & Developers

Tons of code to rewrite. But can be done incrementally.

Dagre-D3

Alternative

• Replace dagre/dagre-d3 with dagre-d3-es #3809

Impact - None?

[wolfspyre]

Regardless of anything else, it's abundantly clear that you're really passionate about Mermaid, @sidharthv96

THAT IS AWESOME. THANK YOU for spending the time and energy to put this together.
Coalescing the why is really important. It helps get everyone oriented in the right direction. It's an oft overlooked, yet incredibly important part of the dev process, and the LACK of investment towards such efforts has led to the demise of many awesome projects.

This is good, HARD, labor. I thank you for doing it.
❤️🐺