search

facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
56.9k stars 8.57k forks source link

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

Open cainmagi opened 3 weeks ago

cainmagi commented 3 weeks ago

Have you read the Contributing Guidelines on issues?

Prerequisites

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'
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

o-l-a-v commented 2 weeks ago

Probably related to this older issue:

slorber commented 2 weeks ago

Thanks for reporting.

Unfortunately, our CI e2e workflow for Yarn PnP doesn't cover the Mermaid theme, as mentioned here: https://github.com/facebook/docusaurus/issues/6157#issuecomment-2461884464

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 (https://github.com/easyops-cn/docusaurus-search-local/pull/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 commented 2 weeks ago

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!

slorber commented 1 week ago

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: