Adding mermaid plugin breaks the document project when Yarn v4 is used and PnP is enabled.

[cainmagi]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

Problem Description

The whole document project will break down when the following conditions are met:

1. @docusaurus/theme-mermaid is used in docusaurus.config.ts.
2. The packages are managed by Yarn 4.
3. The NPM is disabled in .yarnrc, i.e. all packages are linked by Yarn (PnP).

I need to emphasize that this issue only happens if the mermaid plugin is used. If it is not used, there will be no problems.

Background

Yarn v4 provides a very amazing feature. All packages are managed as zipped files in the cache. There will be no need to create another copy of packages like what we have in node_modules folder, which saves a lot of space.

Unfortunately, I spot that Yarn 4 seems to fail to correctly manage the packages compared to npm. If the pacakges are linked by npm, mermaid can work correctly. However, if the packages are linked by the Yarn 4, the same codes will not work. I am not sure whether the problem is caused by Yarn or the design of the mermaid plugin. If the mermaid plugin is the one that can be fixed, it will be good news to me.

Reproducible demo

https://codesandbox.io/p/devbox/objective-framework-rdwmd9

Steps to reproduce

1. Delete the node_modules folder by rm -rf node_modules. If .yarnrc exists, also delete it.

2. In the package.json, add packageManager, @docusaurus/plugin-content-docs, and @docusaurus/theme-mermaid:

   {
     "name": "docusaurus-classic-typescript",
     "packageManager": "yarn@4.5.1",
     "dependencies": {
       "@docusaurus/plugin-content-docs": "3.6.0",
       "@docusaurus/theme-mermaid": "^3.6.0"
     }
   }

3. Turn on the Yarn v4 and install dependencies:

   corepack enable
   yarn set version stable
   yarn install

4. Add mermaid testing codes in the docs/intro.md

    ---
    sidebar_position: 1
    ---
    
    # Tutorial Intro
    
    Let's discover **Docusaurus in less than 5 minutes**.
    
    ## Test mermaid
    
    ```mermaid
    graph TD;
        A-->B;
        A-->C;
        B-->D;
        C-->D;
    ```
   

5. Run the project by yarn start.

Expected behavior

The probject works well if using npm install and npm run start. I think when using yarn install and yarn start, its behavior should be the same.

Actual behavior

Errors

The first error occurs once the index page is loaded. It will happen as long as the mermaid plugin is configured, even if we do not add any mermaid code blocks.

ERROR in ../../root/.yarn/berry/cache/langium-npm-3.0.0-25f5b4ae89-10c0.zip/node_modules/langium/lib/documentation/jsdoc.js 6:0-62
Module not found: Error: Can't resolve 'vscode-languageserver-types' in '/root/.yarn/berry/cache/langium-npm-3.0.0-25f5b4ae89-10c0.zip/node_modules/langium/lib/documentation'

The second error happens when accessing a page having a mermaid block. Certainly, the mermaid block cannot be rendered in this case.

ERROR
Hook useColorMode is called outside the <ColorModeProvider>. Please see https://docusaurus.io/docs/api/themes/configuration#use-color-mode.
ReactContextError
    at useColorMode (webpack-internal:///./.yarn/__virtual__/@docusaurus-theme-common-virtual-917d3c1d99/3/root/.yarn/berry/cache/@docusaurus-theme-common-npm-3.6.0-83186da2f7-10c0.zip/node_modules/@docusaurus/theme-common/lib/contexts/colorMode.js:27:1533)
    at useMermaidConfig (webpack-internal:///./.yarn/__virtual__/@docusaurus-theme-mermaid-virtual-5b4cecc8c9/3/root/.yarn/berry/cache/@docusaurus-theme-mermaid-npm-3.6.0-446303c249-10c0.zip/node_modules/@docusaurus/theme-mermaid/lib/client/index.js:19:303)
    at useMermaidRenderResult (webpack-internal:///./.yarn/__virtual__/@docusaurus-theme-mermaid-virtual-5b4cecc8c9/3/root/.yarn/berry/cache/@docusaurus-theme-mermaid-npm-3.6.0-446303c249-10c0.zip/node_modules/@docusaurus/theme-mermaid/lib/client/index.js:45:35)
    at MermaidRenderer (webpack-internal:///./.yarn/__virtual__/@docusaurus-theme-mermaid-virtual-5b4cecc8c9/3/root/.yarn/berry/cache/@docusaurus-theme-mermaid-npm-3.6.0-446303c249-10c0.zip/node_modules/@docusaurus/theme-mermaid/lib/theme/Mermaid/index.js:18:196)
    at renderWithHooks (webpack-internal:///./.yarn/__virtual__/react-dom-virtual-fb628fc18d/3/root/.yarn/berry/cache/react-dom-npm-18.3.1-a805663f38-10c0.zip/node_modules/react-dom/cjs/react-dom.development.js:15486:18)
    at mountIndeterminateComponent (webpack-internal:///./.yarn/__virtual__/react-dom-virtual-fb628fc18d/3/root/.yarn/berry/cache/react-dom-npm-18.3.1-a805663f38-10c0.zip/node_modules/react-dom/cjs/react-dom.development.js:20098:13)
    at beginWork (webpack-internal:///./.yarn/__virtual__/react-dom-virtual-fb628fc18d/3/root/.yarn/berry/cache/react-dom-npm-18.3.1-a805663f38-10c0.zip/node_modules/react-dom/cjs/react-dom.development.js:21621:16)
    at HTMLUnknownElement.callCallback (webpack-internal:///./.yarn/__virtual__/react-dom-virtual-fb628fc18d/3/root/.yarn/berry/cache/react-dom-npm-18.3.1-a805663f38-10c0.zip/node_modules/react-dom/cjs/react-dom.development.js:4164:14)
    at Object.invokeGuardedCallbackDev (webpack-internal:///./.yarn/__virtual__/react-dom-virtual-fb628fc18d/3/root/.yarn/berry/cache/react-dom-npm-18.3.1-a805663f38-10c0.zip/node_modules/react-dom/cjs/react-dom.development.js:4213:16)
    at invokeGuardedCallback (webpack-internal:///./.yarn/__virtual__/react-dom-virtual-fb628fc18d/3/root/.yarn/berry/cache/react-dom-npm-18.3.1-a805663f38-10c0.zip/node_modules/react-dom/cjs/react-dom.development.js:4277:31)

How to make the error disappear

The following part shows my inspections on this issue. These solutions do not actually fix this issue but can be viewed as a compromission for somehow. I am still looking forward to seeing a real solution. But I do not have an idea to fix it by myself.

Doing any one of the following solutions will make the error disappeared.

Solution 1: Do not use mermaid

If the mermaid plugin is removed from docusaurus.config.ts, the project will work fine. Actually, I have used Yarn 4 and Docusaurus 3 to build several websites without any issues.

Solution 2: Make the packages linked by NPM

If the NPM linker is turned on by adding the following line to .yarnrc, the mermaid plugin will work correctly and the errors will disappear. However, this option brings the large node_modules folder back which is not an ideal solution to me.

nodeLinker: node-modules

Extra comments

I believe that this issue should exist for long. Maybe it firstly occurred when Yarn v4 was available. I spot that a different Docusaurus project met the same issue one year ago. The maintainers of that project solved it by removing the mermaid plugin. See

https://gitlab.com/hoppr/hoppr-docs/-/issues/41

Your environment

• Public source code: Provided in the live demo: https://codesandbox.io/p/devbox/intelligent-mopsa-qdeo7?privacy=public
• Public site URL: (The website is still being developed and not published yet)
  • https://github.com/cainmagi/dash-picture-annotation
• Docusaurus version used: 3.6.0
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
  • Microsoft Edge Version 130.0.2849.68 (Official build) (64-bit)
  • Node v20.17.0
  • Corepack: 0.29.3
  • Yarn: 4.5.1
• Operating system and version:
  • Debian GNU/Linux 12 (bookworm)
  • Docker version: 27.2.0, build 3ab4256
  • Docker image built by
    • https://github.com/cainmagi/dash-picture-annotation/blob/main/Dockerfile
  • Base image: python:3.12-slim
  • Native OS: Windows 11 Enterprise 23H2, 10.0.22631 Build 22631

Self-service

• I'd be willing to fix this bug myself.

[o-l-a-v]

Probably related to this older issue:

• Yarn PNP and TypeScript doesn't compile out of the box #6157

[slorber]

Thanks for reporting.

Unfortunately, our CI e2e workflow for Yarn PnP doesn't cover the Mermaid theme, as mentioned here: #6157 (comment)

Unfortunately, I don't really have the skills and bandwidth to

Hook useColorMode is called outside the .

This error is usually related to duplicate versions of React or other Docusaurus packages, probably @docusaurus/theme-common or @docusaurus/plugin-content-docs. I've seen this too when working on a site upgrade PR (easyops-cn/docusaurus-search-local#468) but I've found it hard to troubleshoot with PnP since I'm not really sure how yarn why works in that mode and how to troubleshoot things in the .yarn folder instead of node_modules

[cainmagi]

Thank you for suggesting the related issues! I have tried adding dependencies in .yarnrc.yml by following your code snippets like this:

packageExtensions:
  "@docusaurus/theme-common@*":
    dependencies:
      "@docusaurus/plugin-content-docs": "*"
  "@docusaurus/theme-mermaid@*":
    dependencies:
      "langium": "*"
  "langium@*":
    dependencies:
      "vscode-languageserver-types": "*"
      "@chevrotain/regexp-to-ast": "*"
      "vscode-jsonrpc": "*"

But it seems that these modifications cannot totally solved the issue.

About the first error

I dug into a little bit deeper for the Module not found: Error. After checking the related codes, I found that the issue may be caused by this:

https://github.com/eclipse-langium/langium/blob/21b105164186dfff6a4763c21d450931e2200e5b/packages/langium/src/utils/cancellation.ts#L8

where the module has a definition like this:

export * from 'vscode-jsonrpc/lib/common/cancellation.js';

It seems that Yarn cannot get the contents of vscode-jsonrpc if the module is exported by export *.

I am not sure why export * does not work. Maybe the usage in langium is bad, or vscode-jsonrpc is not configured correctly for handling the export *.

Important

Should I submit an issue to langium or vscode-jsonrpc for reporting this? Please give me a suggestion. Thank you!

I forked a demo for my attempt to fix this. But it does not totally solve the issue. In this fork, the other Module not found errors are fixed by .yarnrc.yml, but the issues caused by export * still exist.

https://codesandbox.io/p/devbox/frj5lg

About the second error

I need to emphasize that the first error seems to not appear before this version v3.6.0. After falling back to v3.5.2, the errors popping up the index is loaded will not exist.

However, I still need to emphasize that the second error still exists if opening a page with a mermaid block.

I think the second error should exist for very long, because it has been reported in another repository one year ago. So, I think the error Hook useColorMode is called outside the <ColorModeProvider> should be caused by a different reason. At least, the first error is raised by @mermaid-js/parser, but this second error is definitely raised by @docusaurus/theme-mermaid itself. Certainly, if the PnP is disabled by setting nodeLinker: node-modules, this error will disappear.

I made another fork of this test:

https://codesandbox.io/p/devbox/48vf33

Important

I am hoping that these further inspections can help you! If you think this issue would not be solved for long, please feel free to close this issue and reopen it when you think a solution can be found. I will not close it by myself. Thank you!

[slorber]

The 2nd error is very likely related to duplicated packages.

This is not really a bug in Docusaurus itself, and can just happen in any version of it. You have to ensure that you use your package manager correctly so that there's no package duplicates of our core dependencies. I'm not sure how we can prevent that unfortunately.

What we can only guarantee is that our init templates do not produce duplicate dependencies in any of the most popular package managers, which we already do.

Eventually, we could improve DX, fail faster and throw an error telling you that you have duplicate packages, and you should refer to your package manager of choice documentation to deduplicate those. But that remains your responsibility to fix.

---

We can keep this issue open to tracking the problems, but IMHO there's nothing we can do, unless someone has a concrete idea for a fix or an improvement to our codebase I don't have any idea:

• first issue is likely external/mermaid
• second issue is likely external and related to package.json, lockfile, your package manager and its config

[comatory]

Hitting the same problem, I wish there would be easy way to tell which offending package duplicates the libraries.
By the way, I'm using pnpm and AFAIK, it should always provide just single copy of dependency to a project since it hoists the deps to one location.