mermaid 10's ESM only support breaks compat with many apps

[tessus]

I am wondering who came up with the "ESM only" idea and more importantly - why?

Electron doesn't support ESM, which means you just killed Mermaid on every Electron app. I am more than aware that new technology can have a positive effect, but "forcing" it onto people with the awareness that it will break many projects is somehow a weird move.

By "forcing" I mean just making it ESM only without a deprecation phase, nor having a backwards compatible version on the same level in parallel.

As an example, we are using Mermaid in Joplin and the move to ESM only means that we have to stick with Mermaid 9.x until 1) Electron supports it and 2) our code base is also able to support ESM properly.

[mgaitan]

I am the maintainer of sphinxcontrib-mermaid which is used in the documentation of more than a hundred libraries in the Python ecosystem.

For quite some time the default has been to use the "latest" version from a CDN and few people change it because it simply worked. Now that URL generates a 404 because of this change the "mermaid.min.js" doesn't exist. Thus it has broken the documentation of a lot of projects, even though they didn't change anything nor deployed a new version of the docs.

I can either fix my code to avoid using version 10.0 for now or implement the new "ESM" initialization code (I'm a Python developer and have no idea what that means, my apologize). But the truth is that any changes I make to fix the documentations of the users of my software will require them to forcibly update the package version.

I agree that this was a somewhat foolish decision.

[woss]

i have to chip in with the following why are you using the latest in the first place? because why not bind yourself to a specific version? .

The web tech is changing so fast OSS is used everywhere, which means more work for maintainers due to bugs and feature requests. Did you know that only a fraction of OSS maintainers make a salary from the OSS?

I don't know about mermaidjs guys, are they paid for this or not?
But I tell you, as a maintainer myself, it's not easy to work on OSS and paid job.

To go back to my opening line, you'll be perfectly fine if you stick with the version that works for you and NEVER use latest.

[laurent22]

Also the release notes state that "Mermaid is ESM only!", but I don't see any rational for it. What was gained from switching to ESM only? We know what was lost - which is hundreds of hours of development for all projects that depend on the lib, but what was gained?

I know it's an open source project, and you don't owe anything to anybody but when introducing a change that makes your project unusable in many contexts, it makes sense to take a second and discuss with the community why it was done.

[sidharthv96]

CJS has been broken for a while due to D3.

#2559
#2677 (comment)

We had opened #3590 4 months back.

There are methods to support ESM in electron.

---

Adding the following line into any html page will render all elements with class mermaid in it.
<script type="module" src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs">

[tessus]

CJS has been broken for a while due to D3.

I am not sure what you are talking about but we've been using it just fine. The only thing that didn't work was mindmaps, because the mermaid devs changed the rendering algorithm.

We had opened #3590 4 months back.

Hmm, so usually one adds deprecation warnings to new release info and changelog. I can't recall any of those in the release notes since then.

ESM is a bad idea in the first place: ES Modules are terrible, actually · GitHub

[sidharthv96]

I am not sure what you are talking about but we've been using it just fine. The only thing that didn't work was mindmaps, because the mermaid devs changed the rendering algorithm.

I had linked 2 issues below my comment which explains what the issues were.
#4100 was a very recent addition to the set of ESM/CJS issues.

We will still be supporting v9 with security patches.

---

I linked the gist to share some possible fixes, not to argue if ESM/CJS is better.

[laurent22]

#4100 was a very recent addition to the set of ESM/CJS issues.

I assume these issues can be fixed though given pretty much all npm modules are CJS? And if "ESM only!" is fixing something, it's also breaking many other things. It's clear from this particular thread, and that's only a small fractions of affected users.

As for the suggestion of building with Webpack - what sense does that make? The point of ESM is to avoid a build step (apparently), but now that your module is ESM Only we need to add a build step, when none was previously required. Is the lib faster, more reliable, anything? What was gained?

esm is indeed a package that deals with this absurdity but again, more dependencies, more complexity, no gain.

[woss]

fyi anybody tried https://tauri.app/?

I made simple app but didn't use the mermaidjs. worth trying

[angelinekwan]

I am also facing issue with ESM compatibility with Remix app.

[laurent22]

There was a few sensible questions in the original issue - #3590

I find this very tempting but also find it is a hard to understand the consequences for downstream projects.

There was one answer only to that question, and nothing else.

Then the same person asked again:

What I find hard about this is to figure out how this will affect the downstreams projects

No answer to that question.

Are there any important projects that we could check with?

Nobody checked

Something that can break many other projects should be given a bit more consideration - in this particular case the discussion lasted barely a day! Is there really no hope to go back to a CJS version until the drawbacks are better understood?

[simov]

@sidharthv96 can you consider at least releasing one giant non ESM bundle for those of us who cannot use ESM at the moment?

Here is another example: In the new Manifest v3 for Browser Extensions in order to circumvent CSP issues (Content Security Policy) on pages with strict CSP rules, you have to use Content Scripts.

However, those are not regular <script> tags on your web page where you can specify what type of JavaScript you are loading. In fact, they are loaded outside of your web page in an isolated environment for security reasons. And by 'loaded' I mean executed, and since there is no way to specify what type of JavaScript you just loaded, you get the following error message:

Uncaught SyntaxError: Cannot use import statement outside a module (at mermaid.esm.min.js:1:1)

[mrueg]

@sidharthv96 this might be an option how to generate a single file esm bundle that can easily embedded into other applications: golden-layout/golden-layout#654 (comment)

[sidharthv96]

Can you test if mermaid@10.0.3-alpha.1 solves your problems?

Another option is to split the package into two. But that's more maintenance burden on us during releases.

[simov]

@sidharthv96 I can confirm that the dist/marmaid.min.js file found in v10.0.3-alpha.1 works in the exact same way as https://cdnjs.cloudflare.com/ajax/libs/mermaid/9.4.0/mermaid.min.js All 13 diagram types are rendered correctly.

[sidharthv96]

Using the files directly was not the problem. It's when bundlers are introduced that the errors start to popup.

See #4100

[simov]

I see, I was only referring to my own use case in particular - loading Mermaid as a Content Script in a Browser Extension, and also the fact that if we have that bundle back on cdnjs it is going to fix the rest of the problems outlined in this thread - breaking documentation pages and not being available in Electron (if loaded in a web view).

[frehberg]

I can confirm that the dist/marmaid.min.js file found in v10.0.3-alpha.1 works in the exact same way as it did with v9.4.x, many thanks

Usage: Rust crate "aquamarine" https://github.com/mersinvald/aquamarine is embedding the mermaid.min.js into the rustdoc bundle, this way no external dependencies exist when browsing this API doc

[sidharthv96]

We are planning to switch the bundler to esbuild, which doesn't support UMD. There would be an IIFE file, which will ensure <script> tags will continue to work.

Please comment on this thread in case that would break your projects. Thanks!

[sidharthv96]

Released https://www.npmjs.com/package/mermaid/v/11.0.0-alpha.1