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

[snikch]

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

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

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"

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