Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
6 of 7 tasks
cainmagi opened this issue Nov 5, 2024 · 4 comments
Open
6 of 7 tasks
Labels
bug An error in the Docusaurus core causing instability or issues with its execution external This issue is caused by an external dependency and not Docusaurus.

Comments

@cainmagi
Copy link

cainmagi commented Nov 5, 2024

Have you 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": "[email protected]",
      "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'
image

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)

image
image

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

Self-service

  • I'd be willing to fix this bug myself.
@cainmagi cainmagi added bug An error in the Docusaurus core causing instability or issues with its execution status: needs triage This issue has not been triaged by maintainers labels Nov 5, 2024
@cainmagi cainmagi changed the title Adding mermaid plugin break the document project when Yarn 4 is used and the NPM is disabled. Adding mermaid plugin breaks the document project when Yarn v4 is used and the NPM is disabled. Nov 5, 2024
@o-l-a-v
Copy link

o-l-a-v commented Nov 7, 2024

Probably related to this older issue:

@slorber slorber removed the status: needs triage This issue has not been triaged by maintainers label Nov 7, 2024
@slorber
Copy link
Collaborator

slorber commented Nov 7, 2024

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
Copy link
Author

cainmagi commented Nov 7, 2024

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.

image

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

image

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!

@cainmagi cainmagi changed the title Adding mermaid plugin breaks the document project when Yarn v4 is used and the NPM is disabled. Adding mermaid plugin breaks the document project when Yarn v4 is used and PnP is enabled. Nov 7, 2024
@slorber
Copy link
Collaborator

slorber commented Nov 14, 2024

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

@slorber slorber added the external This issue is caused by an external dependency and not Docusaurus. label Nov 14, 2024
xen0n added a commit to xen0n/areweloongyet that referenced this issue Nov 18, 2024
The issue at facebook/docusaurus#10645 seems
unsolvable without upstream changes in langium, so archive the attempt
before disabling Yarn PnP for the time being.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug An error in the Docusaurus core causing instability or issues with its execution external This issue is caused by an external dependency and not Docusaurus.
Projects
None yet
Development

No branches or pull requests

3 participants