Adding mermaid plugin breaks the document project when Yarn v4 is used and the NPM is disabled.

[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.

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