[Docs]: graphql use-in-docusaurus setup steps

[YeHW]

Summary and description

This is the related doc: graphql#use-in-docusaurus. When I setup the docusaurus workspace, I encountered some errors that might relate to compatibility between redwood and docusaurus. Below is a reproducible procedure:

1. Check node and yarn versions.

node -v  # output: v18.16.0
yarn -v  # output: 1.22.19

2. Make a new redwood project.

yarn create redwood-app --ts ./testapp  # prompt if run yarn install, select yes
cd testapp

3. Check dev server.

yarn rw dev  # go to http://localhost:8910, should be a redwoodjs welcome page

4. Add docs to workspaces in the package.json file.

# check the auto-generated package.json file
{
  "private": true,
  "workspaces": {
    "packages": [
      "api",
      "web"
    ]
  },
  "devDependencies": {
    "@redwoodjs/core": "5.3.0"
  },
  "eslintConfig": {
    "extends": "@redwoodjs/eslint-config",
    "root": true
  },
  "engines": {
    "node": "=18.x",
    "yarn": ">=1.15"
  },
  "prisma": {
    "seed": "yarn rw exec seed"
  },
  "packageManager": "yarn@3.6.0"
}

# add docs to workspace
  "workspaces": {
    "packages": [
      "docs",
      "api",
      "web"
    ]
  },

5. Install docusaurus.

npx create-docusaurus@latest docs classic --typescript
# This should output a message: [SUCCESS] Created docs.

6. Check redwood dev server.

yarn rw dev
# There should be a compile error in http://localhost:8910
# ERROR in ../node_modules/@redwoodjs/web/dist/entry/index.js 5:14-41

7. Check docusaurus dev server.

cd docs
yarn start  # should work in http://localhost:3000

I guess docusaurus is set up but it breaks redwood dependencies?

Are you interested in working on this?

• I'm interested in working on this

[YeHW]

@dthyresson Hi, David. I created a reproducible procedure for the problem we discussed in Discord. Could you please help me check if it actually breaks? Thank you!

[dthyresson]

I think I left out a small step and got the order slightly wrong.

1. create new redwood app
2. create a "docs" directory at root
3. add "docs" as workspace in package.json
4. **** important *** cd into "docs" at root
5. now install docusuarus npx create-docusaurus@latest docs classic

This should now have a "docs/docs/" directory structure which I guess is a bit odd. May improve that but the docs/docs is a result of the docs classic arguments

Now:

• you can run yarn rw dev from root to run rw app
• you can cd into "docs/docs" and run npm start to start docusaurus

So my mistake I think is to first cd into docs before running the docusaurus install.

I bet it messes up the react version.

Can you try that and then we can correct the docs?

[dthyresson]

@YeHW Can you confirm that the above works?

Note:

  "workspaces": {
    "packages": [
      "api",
      "web",
      "docs/*"
    ]
  },

I had to use "docs/*" for my workspace.

I am wondering if have the "docs/docs" is too confusing and we either rename the root directory workspace to something like "documentation" and then hav a different directory for the "docs" docusaurus app/site?

[YeHW]

@dthyresson It Still doesn't work with the same error.
But I think I found what caused that.
After some search, I found it might be related to React version.

1. When I ran yarn rw dev, it complained ERROR in ../node_modules/@redwoodjs/web/dist/entry/index.js 5:14-41
2. I checked node_modules/@redwoodjs/web/dist/entry/index.js and found line 5 var _client = require("react-dom/client");, so it complained when requiring "react-dom/client"
3. I found this post. Basically the use of "react-dom/client" is different in React 17 and React 18.
4. The latest redwoodjs requires React 18 but after running npx create-docusaurus@latest docs classic, the React module in node_modules folder got changed to React 17. I confirmed this by excluding node_modules from .gitignore file. The screenshot is the diff between before and after running npx create-docusaurus@latest docs classic for node_modules/react�/package.json file.
   

Though I'm not very familiar with managing node dependencies, is it normal to have break in dependencies after running command like npx create-docusaurus@latest docs classic?

[dthyresson]

Are you working in a new fresh redwood app?

[YeHW]

Are you working in a new fresh redwood app?

Yeah, I start a new app as the procedure in the OP.

[dthyresson]

Strange. The steps I did let me have both a rw dev and Docusaurus served app running simultaneously.

[YeHW]

I tried three kinds of orders and here are the results.
We can use one command grep version {redwood/project/root}/node_modules/react/package.json to check if the node_modules are been modified after executing a command. (Choosing react is because it breaks dependencies)
The setup of the redwood project is the same, using yarn create redwood-app --ts ./testapp.
After that, I tried three orders:

1. The order in the OP, in other words, add "docs" to package.json, then run npx create-docusaurus@latest docs classic --typescript. This results in a break in dependencies. We can verify with the grep command: in a fresh init and yarn install of the redwood project, react version is "version": "18.2.0",, but after the npx command, the version is "version": "17.0.2",.
2. The order as you mentioned, but a bit different: mkdir docs; cd docs; npx create-docusaurus@latest docs classic --typescript. The key is not to add "docs/docs" or "docs/" to the package.json. If so, yarn rw dev in {redwood_project_root}and npm start in the {redwood_project_root}/docs/docs both work as expected. However, if after the npx command, we add "docs/docs" or "docs/" to the {redwood_project_root}/package.json's workspaces, then run yarn install (which allow yarn to manage dependencies again) - This breaks the dependencies again. We can verify by running the grep command before and after add docs/docs to workspace then yarn install step. In addition, after yarn install, yarn rw dev will complain an error.
3. Similar to the second, but before running npx create-docusaurus@latest docs classic --typescript, we add "docs/docs" or "docs/*" to package.json file, then mkdir docs; cd docs; npx create-docusaurus@latest docs classic --typescript will directly throw errors complaining resolving dependencies. As we can see from the error message, docusaurus is not compatible with react@^18.0.0

[INFO] Creating new Docusaurus project...
[INFO] Installing dependencies with npm...
npm WARN ERESOLVE overriding peer dependency
npm WARN ERESOLVE overriding peer dependency
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: @mdx-js/react@1.6.22
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   peer react@"^16.8.4 || ^17.0.0" from @docusaurus/types@2.4.1
npm ERR!   node_modules/@docusaurus/module-type-aliases/node_modules/@docusaurus/types
npm ERR!     @docusaurus/types@"2.4.1" from @docusaurus/module-type-aliases@2.4.1
npm ERR!     node_modules/@docusaurus/module-type-aliases
npm ERR!       dev @docusaurus/module-type-aliases@"2.4.1" from docs@0.0.0
npm ERR!       docs/docs
npm ERR!         docs@0.0.0
npm ERR!         node_modules/docs
npm ERR!       3 more (@docusaurus/plugin-content-docs, ...)
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.13.1 || ^17.0.0" from @mdx-js/react@1.6.22
npm ERR! node_modules/@mdx-js/react
npm ERR!   @mdx-js/react@"^1.6.22" from @storybook/addon-docs@6.5.17-alpha.0
npm ERR!   node_modules/@storybook/addon-docs
npm ERR!     @storybook/addon-docs@"6.5.17-alpha.0" from @redwoodjs/testing@5.3.0
npm ERR!     node_modules/@redwoodjs/testing
npm ERR!       @redwoodjs/testing@"5.3.0" from @redwoodjs/core@5.3.0
npm ERR!       node_modules/@redwoodjs/core
npm ERR!     1 more (@storybook/addon-essentials)
npm ERR!   @mdx-js/react@"^1.6.22" from docs@0.0.0
npm ERR!   docs/docs
npm ERR!     docs@0.0.0
npm ERR!     node_modules/docs
npm ERR!       workspace docs/docs from the root project
npm ERR!   1 more (@docusaurus/theme-classic)
npm ERR!
npm ERR! Conflicting peer dependency: react@17.0.2
npm ERR! node_modules/react
npm ERR!   peer react@"^16.13.1 || ^17.0.0" from @mdx-js/react@1.6.22
npm ERR!   node_modules/@mdx-js/react
npm ERR!     @mdx-js/react@"^1.6.22" from @storybook/addon-docs@6.5.17-alpha.0
npm ERR!     node_modules/@storybook/addon-docs
npm ERR!       @storybook/addon-docs@"6.5.17-alpha.0" from @redwoodjs/testing@5.3.0
npm ERR!       node_modules/@redwoodjs/testing
npm ERR!         @redwoodjs/testing@"5.3.0" from @redwoodjs/core@5.3.0
npm ERR!         node_modules/@redwoodjs/core
npm ERR!       1 more (@storybook/addon-essentials)
npm ERR!     @mdx-js/react@"^1.6.22" from docs@0.0.0
npm ERR!     docs/docs
npm ERR!       docs@0.0.0
npm ERR!       node_modules/docs
npm ERR!         workspace docs/docs from the root project
npm ERR!     1 more (@docusaurus/theme-classic)
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

[YeHW]

Found a similar issue here.