Adding mermaid plugin breaks the document project when Yarn v4 is used and PnP is enabled. #10645
Comments
cainmagi
added
bug
cainmagi
changed the title
|
Probably related to this older issue: |
slorber
removed
the
status: needs triage
|
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
This error is usually related to duplicate versions of React or other Docusaurus packages, probably |
|
Thank you for suggesting the related issues! I have tried adding dependencies in 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 errorI dug into a little bit deeper for the 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 I am not sure why Important Should I submit an issue to I forked a demo for my attempt to fix this. But it does not totally solve the issue. In this fork, the other https://codesandbox.io/p/devbox/frj5lg About the second errorI need to emphasize that the first error seems to not appear before this version 
However, I still need to emphasize that the second error still exists if opening a page with a 
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 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
changed the title
|
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:
|
slorber
added
the
external
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.
Have you read the Contributing Guidelines on issues?
Prerequisites
npm run clearoryarn clearcommand.rm -rf node_modules yarn.lock package-lock.jsonand re-installing packages.Description
Problem Description
The whole document project will break down when the following conditions are met:
@docusaurus/theme-mermaidis used indocusaurus.config.ts..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_modulesfolder, 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 bynpm, 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
Delete the
node_modulesfolder byrm -rf node_modules. If.yarnrcexists, also delete it.In the
package.json, addpackageManager,@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" } }Turn on the Yarn v4 and install dependencies:
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; ```Run the project by
yarn start.Expected behavior
The probject works well if using
npm installandnpm run start. I think when usingyarn installandyarn 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.
The second error happens when accessing a page having a mermaid block. Certainly, the mermaid block cannot be rendered in this case.
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 largenode_modulesfolder back which is not an ideal solution to me.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
3.6.0python:3.12-slimSelf-service
The text was updated successfully, but these errors were encountered: