fix(mermaid): import the bundled ESM build so diagrams render in dev - #74
Merged
Conversation
Diagrams did not render on the Vite dev server. They rendered correctly in a production build, so the problem was invisible to every check in this cycle, which used `astro preview` against built output. Cause: Version 0.14.0 changed the import from an absolute path to the bare `mermaid` specifier. The bare specifier resolves through the package exports map to `dist/mermaid.core.mjs`. That build treats dayjs and other CommonJS packages as externals. A bundler fixes the interop at build time. The dev server does not, so the module throws: The requested module '/node_modules/dayjs/dayjs.min.js' does not provide an export named 'default' The whole mermaid module then fails to load, `mermaid.initialize` never runs, and the raw diagram source shows on the page. Fix: Import `mermaid/dist/mermaid.esm.min.mjs`. That build has its dependencies inlined, so it needs no CommonJS interop. It is a package subpath, not an absolute path, so it resolves in dev and in a build. Verified in docs-styleguide on both paths: - Dev server: `/shared/mermaid/` renders 1 of 1, and `/shared/mermaidwrapper/` renders 3 of 3 with all 3 buttons - Production build and preview: renders 1 of 1 - The view and download buttons still find the SVG - No console errors Four repos consume this component: docs-styleguide, open-payments, rafiki and rafiki-v2, with 63 diagrams between them. All were affected in dev. Reported by Anca on the docs-styleguide PR.
12 tasks
Anca2022
approved these changes
Sep 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mermaid diagrams do not render on the Vite dev server. They render correctly in a production build, so every deploy preview looks right.
Reported by Anca on docs-styleguide#119.
Cause
0.14.0 changed the import:
The bare specifier resolves to
dist/mermaid.core.mjs. That build treats dayjs as an external CommonJS package. A bundler fixes the interop. The dev server does not, so the module throws:Mermaid never loads,
initializenever runs, and the raw diagram source shows on the page.Fix
This build inlines its dependencies, so it needs no interop. It is a package subpath, not an absolute path, so it resolves in dev and in a build.
Scope
This is not specific to Astro 7. The same failure occurs on Astro 6.3.8 with Vite 7, on a clean install. The mermaid version does not matter either, because 11.15.0 and 11.17.2 both map
mermaidto the same file.Four repos use this component, with 63 diagrams between them: rafiki 35, open-payments 18, docs-styleguide 8, rafiki-v2 2. All fail on the dev server. No deployed site is affected.
Verified
In docs-styleguide, on a cold cache:
/shared/mermaid//shared/mermaidwrapper/Console is clean.
pnpm lintpasses.After merge
Publish 0.14.1, then refresh the lockfile on the four consumer PRs. Their ranges read
^0.14.0, which accepts 0.14.1, but a committed lockfile holds the old version.