feat(md): support mermaid

[AugustinMauroy]

Description

Support mermaid and add stories

Related Issues

close #7540

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run npm run format to ensure the code follows the style guide.
• I have run npm run test to check if all tests are passing.
• I have run npx turbo build to check if the website builds without errors.
• I've covered new added functionality with unit tests if necessary.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
nodejs-org	❌ Failed (Inspect)		Mar 17, 2025 5:25pm

[Copilot]

PR Overview

This PR adds support for mermaid diagrams in MDX content and enhances the design system with a corresponding Storybook story.

• Implements a new Storybook story for mermaid diagrams.
• Integrates and enforces plugin ordering for the rehypeMermaid into the MDX pipeline.

Reviewed Changes

File	Description
apps/site/components/design/mermaid.stories.tsx	Adds a Storybook story to render mermaid diagrams via MDX compilation.
apps/site/next.mdx.plugins.mjs	Inserts the rehypeMermaid plugin with explicit ordering instructions.

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

[AugustinMauroy]

Issue here, is that we need playwright to render the diagram in back-end. So what do you think about this aproche.

[flakey5]

Issue here, is that we need playwright to render the diagram in back-end. So what do you think about this aproche.

I mean there is also #7395, so this could help with both things

[github-actions]

Unit Test Coverage Report

Lines	Statements	Branches	Functions
	88.75% (742/836)	76.1% (242/318)	87.65% (142/162)

Unit Test Report

Tests	Skipped	Failures	Errors	Time
182	0 💤	0 ❌	0 🔥	5.749s ⏱️

[ovflowd]

FYI @AugustinMauroy build is failing:

@node-core/website:build: TypeError: {}.resolve is not a function
@node-core/website:build:     at <unknown> (.next/server/chunks/9603.js:9:50830)
@node-core/website:build: 
@node-core/website:build: > Build error occurred
@node-core/website:build: [Error: Failed to collect page data for /sitemap.xml] { type: 'Error' }
@node-core/website:build: npm error Lifecycle script `build` failed with error:
@node-core/website:build: npm error code 1
@node-core/website:build: npm error path /vercel/path0/apps/site
@node-core/website:build: npm error workspace @node-core/website
@node-core/website:build: npm error location /vercel/path0/apps/site
@node-core/website:build: npm error command failed
@node-core/website:build: npm error command sh -c cross-env NODE_NO_WARNINGS=1 next build
@node-core/website:build: ERROR: command finished with error: command (/vercel/path0/apps/site) /node22/bin/npm run build exited (1)
@node-core/website#build: command (/vercel/path0/apps/site) /node22/bin/npm run build exited (1)

[AugustinMauroy]

FYI @AugustinMauroy build is failing:

yeah I know it's maybe a upstream issue.

[ovflowd]

FYI @AugustinMauroy build is failing:

yeah I know it's maybe a upstream issue.

That ain't a valid reasoning. Please investigate :)

[AugustinMauroy]

That ain't a valid reasoning. Please investigate :)

yeah I mean I'm on it

[AugustinMauroy]

Okay update on this issue it's because next doesn't understand import.meta.resolve.
potential solution:

• creating a babelrc.json an changing behavor of next
• using a webpack loader
• i create a new plugin that doesn't use this API

[ovflowd]

It is not a Next.js problem. More like a SWC issue. It understands what import.meta is but it asks to use deconstruction rather than direct access.

[AugustinMauroy]

From my research swc handle it correctly but it's webpack/turbopack when they bundle there are something wrong

[ovflowd]

From my research swc handle it correctly but it's webpack/turbopack when they bundle there are something wrong

It can't be webpack (or imo the chances are slim), nor turbopack (turbo is not even used for prod builds)

Id recommend opening an issue on swc repo or next.js repo even and ask about this.

Otherwise make a fork of the plugin and make the changes :)

[AugustinMauroy]

Okay, here's the current status:

1. I forked the package that was misunderstood by Next.js
2. I patched it using api node (which in many cases is not the best idea, better to use ESM resolution chain)
3. I overrode the dep to use the local version
   Still to be fixed:

• dark theme
• storybook
• build issue (need to build package => re install => build app)

[avivkeller]

I don't think it's practical to add tens of thousands of lines of code just to support Mermaid. Maintaining all these additions ourselves wouldn't be realistic.

Instead, such changes should be handled through upstream PRs or forks.

[AugustinMauroy]

Okay let's me explain why this choice.
The issue come from Next.js with SWC/Bundler so we cannot fix it on our side.
Your solution of patching upstream package cannot work because the package didn't have any issue.
So two solution was possible fork it and publish it to NPM or include it on our monorepo.
Why not publish it to npm mainly because it's a temporary solution by waiting Next.js to fix their issue.

[avivkeller]

Why not publish it to npm mainly because it's a temporary solution by waiting Next.js to fix their issue.

I think that we should either open or monitor an issue on Next.js, and put mermaid on hold until that is resolved.

I just can't realistically see us maintaining such a large (and not written by us) codebase, even if it's only temporary

[AugustinMauroy]

I think that we should either open or monitor an issue on Next.js, and put mermaid on hold until that is resolved.

Already done !

I just can't realistically see us maintaining such a large (and not written by us) codebase, even if it's only temporary

"Huge" without test and fixture the patched package took 3 files

[avivkeller]

On a different note, I'm not too keen on supporting Mermaid this way, as it prevents the website from being "out-of-the-box" buildable. Users would need to have a Playwright browser installed on their machine (right?), which, if I recall correctly, can take up to a gigabyte of space.

That said, I submitted a PR to mermaid-isomorphic that should address the issue.

remcohaszing/mermaid-isomorphic#13

[remcohaszing]

Sadly you need a proper DOM environment to render Mermaid diagrams. I also considered JSDom, but that won’t work, because it doesn’t support node dimensions.

Another approach would be to use the pre-mermaid strategy, but then you need to include Mermaid in the client side bundle.

[AugustinMauroy]

Another approach would be to use the pre-mermaid strategy, but then you need to include Mermaid in the client side bundle.

The issue with that is Next.js actually try to bundle everything include if you specify pre-mermaid

[remcohaszing]

That’s true. Webpack will still import and process mermaid-isomorphic if you use the pre-mermaid approach. But you can stub it. All you need is something like:

export function createMermaidRenderer() {
  // This is an empty stub
}

And alias mermaid-isomorphic to that file in the Webpack config.

I don’t think this is ideal, but it would at least enable you to use Mermaid diagrams.

My personal recommendation as an MDX maintainer would be to replace all custom MDX compilation logic with @next/mdx. Then you can specify rehype-mermaid in next.config.js, without having to deal with any Next.js module resolution quirks.

[avivkeller]

Sadly you need a proper DOM environment to render Mermaid diagrams.

Okay. In that case, disregard what I said about playwright–i guess it's required

Another approach would be to use the pre-mermaid strategy, but then you need to include Mermaid in the client side bundle.

In my opinion, bundling a entire mermaid renderer in the client-side bundle is unnecessary and bloated for the client. Instead, we should use a package like the ones that @remcohaszing created.

My personal recommendation as an MDX maintainer would be to replace all custom MDX compilation logic with @next/mdx. Then you can specify rehype-mermaid in next.config.js, without having to deal with any Next.js module resolution quirks.

Interesting, @ovflowd is this possible?

---

@remcohaszing is there a way you can patch your library to not use import.meta.resolve? Maybe via a stub package?

That should resolve the issues we are facing, right?

[remcohaszing]

@remcohaszing is there a way you can patch your library to not use import.meta.resolve? Maybe via a stub package?

That should resolve the issues we are facing, right?

I really don’t see how. mermaid-isomorphic works by:

• Starting a playwright browser.
• Opening an HTML file, which needs to be resolved as a relative path.
• Injecting the Mermaid UMD script, which needs to be resolved from a dependency in node_modules.
• Injecting the FontAwesome CSS, which needs to be resolved from a dependency in node_modules.
• Some magic to ensure consistent results ✨
• Rendering the Mermaid diagrams in the prepared page.

rehype-mermaid then wraps this in a rehype plugin for compatibility with rehype / MDX.

So it really needs to resolve things on the file system somehow.

[avivkeller]

Got it! Thanks again for your insight!

I still feel that drastically increasing our codebase and using dependency overrides isn’t the best solution, so I’ll continue to keep this PR blocked for now.

[ovflowd]

If this increases our codebase drastically or the client bundle drastically, it is not worth it.

We should not bloat our bundles for something used in one blog post.

Edit by @avivkeller: Missing word