Cannot load docs from outside local package root when running as a Yarn workspace

[snikch]

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

When adding Docusaurus as a workspace in a Yarn 2+ project, the docs plugin will not loads docs from outside the Docusaurus project root. Instead, an import error message is displayed for each markdown file.

Module not found: Error: Can't resolve '@mdx-js/react' in '/home/mal/code/src/github.com/snikch/docusaurus-workspace-import-repro/docs'
Module not found: Error: Can't resolve 'react/jsx-runtime' in '/home/mal/code/src/github.com/snikch/docusaurus-workspace-import-repro/docs'

├── README.md
├── docs
│   ├── intro.md
│   ├── tutorial-basics
│   └── tutorial-extras
├── package.json
├── packages
│   └── docs
│       ├── README.md
│       ├── babel.config.js
│       ├── docusaurus.config.js
│       ├── package.json
│       ├── sidebars.js
│       ├── src
│       │   ├── components
│       │   ├── css
│       │   └── pages
│       └── static
└── yarn.lock

// package.json
{
  "name": "docusaurus-workspace-import-repro",
  "packageManager": "yarn@4.1.1",
  "workspaces": [
    "packages/*"
  ]
}

A reproduction is available here: https://github.com/snikch/docusaurus-yarn-workspace-repro
An example without Yarn workspaces which shows loading a directory above works fine is available on the working branch.

Yarn Workspace	Dir Moved	Works
Y	N	✅
Y	Y	❌
N	Y	✅
N	N	✅

Reproducible demo

https://github.com/snikch/docusaurus-yarn-workspace-repro

Steps to reproduce

• git init
• yarn init -2 -w
• yarn create docusaurus docs classic packages
• mv packages/docs/docs .
• sed -i 's/sidebarPath/path: "../../docs",\n sidebarPath/' packages/docs/docusaurus.config.js
• yarn workspace docs start

Expected behavior

Docusaurus starts and renders docs pages.

Actual behavior

Docusaurus cannot render markdown docs due to import issues.

Your environment

• Public source code: https://github.com/snikch/docusaurus-yarn-workspace-repro
• Public site URL:
• Docusaurus version used: 3.1.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node.js v20.9.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Ubuntu WSL2

Self-service

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

[slorber]

Docusaurus docs are transpiled by MDX to React components.
This also means that some dependencies must be found in a parent node_module folder of the docs, otherwise those "MDX React components" do not find the appropriate dependencies.

The key thing to understand is that your docs are like React code, and the appropriate dependencies must be available to them.

This usually works fine with most monorepo tools, because they would hoist the dependencies at the top of your monorepo node_modules, but won't work with Yarn PnP system.

Yarn 2+ uses a Plug and Play mode by default, which behaves a bit differently than traditional monorepo tools, and is "stricter"

You can use any of those solutions to fix the problem under Yarn 2+:

Disable PnP mode:

yarn config set nodeLinker node-modules
yarn install
yarn workspace docs start

Hoist the dependencies at monorepo root yourself

yarn add @mdx-js/react@npm:3.0.1 react@npm:18.2.0
yarn workspace docs start

Unfortunately it's hard for us to make Docusaurus work out of the box with all monorepo tools and fancy setups users might attempt to use, but the general idea remains that the appropriate dependencies should be available to docs, no matter how those dependencies get wired.

[snikch]

@slorber thank you for your quick and detailed reply. Hoisting the imports to the root has some difficulties but we've managed to get a "good enough" version working.

We've lost things like prism code syntax highlighting and admonitions. I assume this is likely the same issue and I need to hoist a variety of other packages. I tried with these but it still didn't seem to work. Does anything come to mind?

yarn add @docusaurus/preset-classic @docusaurus/plugin-content-docs @docusaurus/core prism-react-renderer

[slorber]

To be honest I don't really have any expertise in Yarn PnP system and don't use it myself 😅

I remember it was challenging to get our e2e tests pass under PnP but it's mostly @Josh-Cena that fixed those as far as I remember.

Afaik there are several options you can try, such as:

• pnpMode: "loose"
• pnpFallbackMode: "all"

[snikch]

Thanks @slorber. Neither of those options helped, but I'll look into this deeper when I have time. We're in a "good enough" state for now. I appreciate your help so far ❤️ .

[slorber]

Great 👍

Maybe @arcanis could help you, he's using Docusaurus on the Yarn website and probably knows how to handle this situation better than I do 😄

[snikch]

Nice, keen to hear more on how people have solved / worked around this!

I guess it might make sense to add a little more info on the reasoning for including docs outside the actual docusaurus website. I run two docs websites which document a monorepo using Yarn workspaces. In both cases I actually want to include documentation directly from the package README's.

e.g. a monorepo structured like this;

├── apps
│   ├── app.xxx.com
│   ├── contributors.xxx.com <- 🦖
│   └── graphql.xxx.com
└── packages
     ├── cli
     ├── db-app
     ├── email
     ├── graphql
     ├── log
     ├── otel
     ├── services
     └── ui

in my docusaurus navigation I have a main menu item of "packages" which then contains the documentation for each individual package. I find this pattern works really well as it allows us to keep the README's as the central documentation for each package.

[oliveirarafa]

I'm using npm workspaces with nx and i'm facing a similar problem.

I can't import a react component library to use on the live editor, but if I take my site outside the monorepo it works.

[slorber]

@oliveirarafa this issue is about Yarn PnP and not related to the live editor. What you encounter is probably unrelated and we'd need a minimal https://docusaurus.new/stackblitz repro to investigate as a separate issue.