Migrate to React 18

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

For site maintainers

Upgrading to React 18 is optional—it won’t break anything, but it won’t do anything either. Until Docusaurus uses the new createRoot API, the site’s behavior will still be the same as that in React 17. However, you may be able to use a few React 18 niceties like useId() (which I’m personally excited about for accessibility reasons).

If your dependency management bot wants to upgrade to React 18 for you, and it doesn’t cause any problems (around peer dependencies), feel free to accept it.

Motivation

Unlike React 17, React 18 contains actual API changes that may not be backward-compatible (i.e. you can’t take a React 18 program and expect it to run in a project installed with React 17). Therefore, migration to React 18 can only happen along two paths:

1. We migrate to React 18 by using the new createRoot API, and throw an early error for anyone still installed with react@17, telling them to update their package.json.
   • Problem: breaks virtually every site, some sites already having a version of React in their monorepo may end up having duplicate copies, which opens a can of worms.
2. We detect the version of React installed, and selectively uses ReactDOM.render or createRoot based on the version.
   • Problem: hacky code, slightly increases bundle size, and harder to maintain in the long run (refactoring hazards)

It is not good to move forward with either solution.

We have some preliminary work done in #7102, but it’s far from being complete, and gets stalled in multiple places. The resolution is that as the 2.0 release is approaching, we’ll likely stay on React 17 because the truth is, even many libraries are not fully prepared for React 18 yet! React 18 will be considered a breaking change and will come in v3.

The most urgent blocking issue is that MDX v1 doesn’t declare React v18 in its peer dependencies range. Because the v1 line is effectively frozen, I believe there’s no plan to fix this. Certain package managers (namely, npm v7 and pnpm) are strict about peer dependencies and will refuse to install properly if @mdx-js/react is installed alongside react@18. This will be confusing for the users, so it’s another strong point why we’ll delay it to v3: we’ll only migrate to MDX v2 in Docusaurus v3 (#4029).

Since I don’t think React 18 actually removed any API, there’s not much we need to do on the code side. It’s only about dependencies. Still, it would be nice if we can remove react-loadable (#3841), because it uses the deprecated componentWillMount lifecycle and prevents us from opting into StrictMode. Also, React 18 will bring support for new SSG APIs (including server-rendering Suspense), and we’ll want to take the opportunity of prolonged migration time window to look into that as well.

Self-service

• I’d be willing to do some initial work on this proposal myself.

[juliusmarminge]

When can we expect the first canary release that uses React 18? Saw that you have 3.0.0-alpha.0 but it’s still on React 17?

[Josh-Cena]

We hope to release Docusaurus v3 very quickly. According to our release doc, it should be within a few months, so you should not worry about it too much. React 18 will be a major change, so no, it will not be backported. Also, we have abstracted all the build pipeline, and we hope you could develop without caring about the underlying plumbing infra.