Use ESBuild (replaces UMD with IIFE bundle)

[sidharthv96]

📑 Summary

Replace vite with esbuild for builds.
Vite will be used for coverage builds.

📏 Design Decisions

🚀 speed.

# Full Build
ESBuild -> nr build  11.38s user 1.09s system 226% cpu 5.497 total
Vite    -> nr build  31.84s user 3.15s system 170% cpu 20.535 total
# JS only build
ESBuild -> nr build:esbuild  4.49s user 0.68s system 241% cpu 2.143 total
Vite    -> nr build:vite  24.21s user 2.57s system 163% cpu 16.402 total

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added unit/e2e tests (if appropriate)
• 📓 have added documentation (if appropriate)
• 🔖 targeted develop branch

[sidharthv96]

We could release the mermaid-mini bundle without elk and cytoscape. The size difference is significant.
But, that was a POC, we need to properly discuss on how and if we should do it.

Simply adding the dependencies to external does the job. We need a way to inform the user why the diagram renders fail though. Even better, if we could dynamically avoid bundling the diagrams, that would save more space.

@Yokozuna59 this would help you with vscode dependencies too.

[codecov]

Codecov Report

Merging #4729 (8f44de6) into next (43217e1) will decrease coverage by 25.49%.
The diff coverage is n/a.

Additional details and impacted files

@@             Coverage Diff             @@
##             next    #4729       +/-   ##
===========================================
- Coverage   71.57%   46.09%   -25.49%     
===========================================
  Files         116       53       -63     
  Lines       12709     6736     -5973     
  Branches      549       32      -517     
===========================================
- Hits         9097     3105     -5992     
- Misses       3495     3630      +135     
+ Partials      117        1      -116     

Flag	Coverage Δ
e2e	?
unit	46.09% <ø> (ø)

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

see 111 files with indirect coverage changes

[sidharthv96]

@aloisklink changing vite's umd -> iife did work for mermaid, but had issues for other packages. So, it'll need more changes, which is more work that will be removed in the next commit.

So, I have squashed all the commits from the old branch to this one.

[aloisklink]

This PR looks good to me!

Simply adding the dependencies to external does the job.

IMO, I think it would be better to completely remove the mindmap and flowchart-elk diagrams instead of doing this. But we'd first have to split them into separate @mermaid-js/mermaid-mindmap and @mermaid-js/flowchart-elk NPM packages, which would take quite a bit of work, see #4120

Todo before merging

• Can you change the .vite/jsonSchemaPlugin.ts path to .build/jsonSchema.ts in:

  • mermaid/packages/mermaid/src/schemas/config.schema.yaml

    Line 10 in 43217e1

    # - `.vite/jsonSchemaPlugin.ts`

  • mermaid/packages/mermaid/src/schemas/config.schema.yaml

    Line 24 in 43217e1

    # you may need to add it to `.vite/jsonSchemaPlugin.ts` and `src/docs.mts`

• How are we going to document the BREAKING CHANGE that the UMD dist/mermaid.min.js is now an IIFE dist/mermaid.min.js file?
  • This must be in the PR description (I'd even recommend sticking this in the commit description if you can, if you're comfortable with git rebase)
  • Maybe we also need a label for PRs to that says BREAKING CHANGES?
  • Can we stick this in the PR title too? Something like Use ESBuild (replaces UMD with IIFE bundle)
• When to merge: Do we have a rough timeline on when we'd release v11? If it's going to be a long way in the future, I'd recommend holding back on merging this until closer to v11, just because it's always easier to fix merge conflicts in PRs, rather than in the main/develop/next branches.

Also, this is a pretty minor nit-pick, but generally a change like this won't be a feat:, but instead it would be a build: or chore:, since it's not a feature to users of Mermaid. It's mainly just for mermaid developers.

[sidharthv96]

IMO, I think it would be better to completely remove the mindmap and flowchart-elk diagrams instead of doing this.

The define feature could be used to avoid the import of these without breaking them to separate modules. We could use define to replace that import with a custom error diagram import, which mentions they are using a smaller version of mermaid and some diagrams are not available in that.

[sidharthv96]

When to merge: Do we have a rough timeline on when we'd release v11? If it's going to be a long way in the future, I'd recommend holding back on merging this until closer to v11, just because it's always easier to fix merge conflicts in PRs, rather than in the main/develop/next branches.

This, Langium and your type change are the only changes that we have planned for v11.
Langium has a hard dependency on this. And the DX of esbuild is unmatched by vite (so we're defenitely keeping esbuild, atleast of the dev if any major issue occurs). So, I think we should merge this into next now, so that langium PRs can be targeted to next. None of the changed file in this PR seems to be "hot" files, so merge conflicts might not be a major issue.

[sidharthv96]

How are we going to document the BREAKING CHANGE that the UMD dist/mermaid.min.js is now an IIFE dist/mermaid.min.js file?

Top of the changelog like V10 is mandatory.

This must be in the PR description (I'd even recommend sticking this in the commit description if you can, if you're comfortable with git rebase)

Done

Maybe we also need a label for PRs to that says BREAKING CHANGES?

Aren't all PRs to next considered breaking?
https://github.com/mermaid-js/mermaid/pulls?q=is%3Apr+base%3Anext

Can we stick this in the PR title too? Something like Use ESBuild (replaces UMD with IIFE bundle)

Done

[aloisklink]

Top of the changelog like V10 is mandatory.

Sounds good!

Maybe we also need a label for PRs to that says BREAKING CHANGES?

Aren't all PRs to next considered breaking?

A PR to next is considered breaking for us reviewers, but I don't know if it will be clear to the average person, which is why we need to explain why it's a breaking change in the PR description!

Also, if we make a BREAKING CHANGES label, we can stick it into the .github/release-drafter.yml file and it should automatically stick it into a ⚠️ BREAKING CHANGES ⚠️ section in the Release notes.

The Mermaid project doesn't have great Release Notes, (even I sometimes struggle to realize what's changed when I'm maintaining the mermaid-cli library). Breaking changes are very important, so hopefully then whoever makes the release (maybe @knsv?), they'll see the BREAKING CHANGES bit and won't accidentally make a MINOR/PATCH release, and they'll remember to also update the CHANGELOG.md file (if we're doing that).

[sidharthv96]

[aloisklink]

Hmmm, I don't think we need the Minor/Patch labels, since I feel like Type: Enhancement/feature and Type: Bug/Error/fix should already cover these (since a Semver minor change is something that we added, and a semver patch change is just a fix). Maybe it's worth re-opening #4444, even if this is more to do with PRs than issues.

[sidharthv96]

Done :)