Esbuild: backwards-compatible mermaid.core.mjs

[aloisklink]

📑 Summary

Note: This PR targets sidv/esbuild, aka PR #3386

The mermaid.core.js build was previously a UMD build that did not have node_modules bundled.

This was designed for users to add mermaid to their own apps, then bundle with Webpack/ESBuild. Hence the bundle test in cypress/platform/bundle-test.js.

After this PR, there will be three different types of files in the dist/ folder:

• mermaid{.min}.js - Minified Bundled IIFE - For use in browsers from a CDN that don't support ESM yet.
• mermaid.esm{.min}.mjs - Minified Bundled ESM - For use in browsers from a CDN that do support ESM.
• mermaid.core.mjs - Minified unbundled ESM. For use when creating your own apps using NPM/yarn. Does not bundle node_modules/, as your Webpack/ESBuild/vite should bundle them.

📏 Design Decisions

I had to slightly modify the .jison parser, as by default it adds an unused main() that has a require("fs");. As this main() function is never used, I've just overrode it with an empty function.

Possible breaking change (low risk)

As ESBuild does not support UMD, I've switched the mermaid.core.js to instead use ESM at mermaid.core.mjs, as Mermaid now requires ESM (due to d3 requiring ESM).

The switch from UMD to ESM shouldn't break anybody's configuration, because since Mermaid 8.12.0, ESM has been required due to d3 requiring ESM (see #2677).

Switching from .core.js to .core.mjs probably won't cause any issues, since most people would use import mermaid from "mermaid", and their bundler would automatically find the file by looking at the package.json file.

• A quick code search of mermaid.core.js: https://github.com/search?p=1&q=mermaid.core.js&type=Code
  • Everything I can see there is just auto-generated files, so I don't think this will cause any issues.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added unit/e2e tests (if appropriate)
  • Tested in cypress/platform/bundle-test.js
  • I've also tested this with https://github.com/mermaid-js/mermaid-live-editor
    I've confirmed that yarn dev works after running yarn add git+https://github.com/aloisklink/mermaid.git#esbuild-backwards-compatible-core-js.
• 🔖 targeted develop branch
  • I've targeted sidv/esbuild, aka PR ESBuild #3386

[sidharthv96]

Wow! I knew something was not really right with my approach, but didn't really know what. Was keeping the esbuild PR open because of that.

@aloisklink, can you suggest some tests we can add to makes sure downstream versions of mermaid doesn't break when we make changes like this? (Or atleast we know what breaks?).

The categories that I can think of:

Type	Integration	Examples
Projects that use bundlers.	import mermaid from 'mermaid'	Live editor
Websites that integrate directly using src	<script src="url/mermaid.min.js">	Mermaid documentation site
Websites that integrate directly using src (esm)	<script src="url/mermaid.min.mjs" type="module">	?

What other approaches might there be?

[aloisklink]

Wow! I knew something was not really right with my approach, but didn't really know what. Was keeping the esbuild PR open because of that.

To be honest, it wasn't super obvious to me either. I had to do a bit of searching through the git history to realize what mermaid.core.js was actually doing. Hopefully the comments will make things more obvious!

@aloisklink, can you suggest some tests we can add to makes sure downstream versions of mermaid doesn't break when we make changes like this? (Or atleast we know what breaks?).

This PR fixes the test for mermaid.core and Webpack, and cypress/platform already has a lot of IIFE tests. It should be pretty easy to add an ESM test too.

They're not 100% perfect, but those basic tests should cover all the obvious bugs 😄

import mermaid from 'mermaid'

Tested by:

• https://github.com/mermaid-js/mermaid/blob/9d0901801b0cfa2c14afda256e70bcc08b91038d/cypress/platform/bundle-test.js
  It still seems to be using webpack config, see

  mermaid/.webpack/webpack.config.e2e.babel.js

  Line 9 in 9d09018

  'bundle-test': './cypress/platform/bundle-test.js',

<script src="url/mermaid.min.js">

Tested everywhere in cypress/platform/*.html
For example:

mermaid/cypress/platform/gitgraph.html

Line 109 in 9d09018

<script src="./mermaid.js"></script>

<script src="url/mermaid.min.mjs" type="module">

It doesn't look like this is tested anywhere currently.

I think we can just add another .html file to cypress/platform/ that uses <script src="url/mermaid.min.mjs" type="module">. We might also need to make a new .esbuild/serve.cjs config so that the ESM build is also hosted.

[jayhamilton]

I am attempting to use ngx-markdown within Angular 15+. The instructions indicate to install the npm package for mermaid and then add the mermaid.min.js to the scripts array within angular.json. With the version of mermaid I installed, which is probably the most current version, there is no mermaid.min.js. I am a bit new to esm, webpack and Angular in terms of bundling and modules. Not sure this is the correct place but any suggestions on how to use the most current mermaid scripts within Angular 15+? I am contemplating getting the file from the CDN but just wanted to see if someone can steer me in the correct direction in terms of loading esm files (I guess) within Angular.

[aloisklink]

Hi @jayhamilton, there's a PR open to add back a single-file UMD mermaid.min.js, #4281.

Hopefully it will get merged, and you'd just be able to use the same old instructions with the next Mermaid release!

Otherwise, you might have better luck asking at https://stackoverflow.com/questions/tagged/angular or the ngx-markdown repo!