Docusaurus Faster

Docusaurus v3.6 is out with the Docusaurus Faster options 🥳 🎉

https://docusaurus.io/blog/releases/3.6

# Docusaurus Faster

This is a meta-issue for the Docusaurus Faster project.

The goal is to modernize our infrastructure and greatly reduce the time and memory it takes to build a Docusaurus site in production mode, to fix this long-standing issue https://github.com/facebook/docusaurus/issues/4765.

```bash
yarn add @docusaurus faster
```

Before using these flags, you will need to add an extra package encapsulating all the opt-in dependencies:

It includes multiple experimental PRs adding new `siteConfig.future.experimental_faster` options:

- [`swcJsLoader`](https://github.com/facebook/docusaurus/pull/10435): Use [SWC](https://swc.rs/) to transpile JS (instead of [Babel](https://babeljs.io/)).
- [`swcJsMinimizer`](https://github.com/facebook/docusaurus/pull/10441): Use [SWC](https://swc.rs/) to minify JS (instead of [Terser](https://github.com/terser/terser)).
- [`swcHtmlMinimizer `](https://github.com/facebook/docusaurus/pull/10554): Use [SWC](https://swc.rs/) to minify HTML and inlined JS/CSS (instead of [html-minifier-terser](https://github.com/terser/html-minifier-terser)).
- [`lightningCssMinimizer`](https://github.com/facebook/docusaurus/pull/10522): Use [Lightning CSS](https://lightningcss.dev/) to minify CSS (instead of [cssnano](https://github.com/cssnano/cssnano) and [clean-css](https://github.com/clean-css/clean-css)).
- [`rspackBundler`](https://github.com/facebook/docusaurus/pull/10402): Use [Rspack](https://rspack.dev/) to bundle your app (instead of [webpack](https://webpack.js.org/)).
- [`mdxCrossCompilerCache`](https://github.com/facebook/docusaurus/pull/10479): Compile MDX files only once for both browser/Node.js environments instead of twice.
- [`ssgWorkerThreads`](https://github.com/facebook/docusaurus/pull/10826) (🆕 v3.8+): Uses a Node.js Worker thread pool to optimize CPU usage during SSG.
- [`rspackPersistentCache`](https://github.com/facebook/docusaurus/pull/10931) (🆕 v3.8+): Uses [Rspack Persistent Cache](https://rspack.dev/blog/announcing-1-2#persistent-cache) to rebuild your site much faster.
- [`gitEagerVcs`](https://github.com/facebook/docusaurus/pull/11512) (🆕 v3.10+): Implements a new "git-eager" VCS strategy for reading Git commit info for the `showLastUpdateAuthor` and `showLastUpdateTime` plugin options. This reads the whole Git repository upfront instead of issuing thousands of `git log ` shell calls.

```js
const config = {
future: {
experimental_faster: {
optionName: true
},
},
}
```

We recommend turning them on all at once with a simple boolean shortcut. We also recommend turning [`future.v4`](https://docusaurus.io/docs/next/api/docusaurus-config#future:~:text=%2C%0A%7D%3B-,v4,-%3A%20Permits%20to%20opt) feature flag on, because some Docusaurus Faster options rely on upcoming changes.

```js
const config = {
future: {
v4: true, // opt-in for Docusaurus v4 planned changes
experimental_faster: true, // turns Docusaurus Faster on globally
},
}
```

But you can also turn them on/off one by one to troubleshoot potential problems.

Note that the `rspackBundler` option requires `swcJsLoader`, `swcJsMinimizer`, and `lightningCssMinimizer` to be enabled first.

It is possible that certain combinations of options do not work, and our CI doesn't cover all possible permutations (only `true` / `false`).

It also includes notable memory improvements:
- Rspack takes much less memory to bundle your app
- [Fix important memory leak affecting i18n sites](https://github.com/facebook/docusaurus/pull/10599)

## What to expect

With `experimental_faster: true`, our Docusaurus website builds:
- ~ 3-4x faster on cold builds 🔥
- ~ same on hot re-builds (because [Rspack doesn't support persistent cache yet](https://rspack.dev/misc/planning/roadmap#persistent-cache))
- the Rspack bundling consumes much less memory

Although rebuilds (with warm `./node_modules/.cache`) are not faster (yet), we recommend you enable the `experimental_faster: true` option to future-proof your site against our new dependencies and report us potential problems you encounter.

Our core plugins/themes are all compatible with this new option, and we expect most community plugins to be compatible out-of-the-box. Some plugins might need minor adjustments to make them compatible with Rspack, and we'll help the community to make our ecosystem compatible with Rspack.

This option is relatively safe to use in production: we have deployed our own website with it already:
- If your Docusaurus site is standard, it should be fine out of the box
- If your Docusaurus site is more complex, make sure to test it thoroughly and give us feedback

## For Docusaurus plugins authors

Some plugins implementing the `configureWebpack()` lifecycle hook might need to adjust their code to add support for Rspack.

I will write a guide for them in this sister issue: https://github.com/facebook/docusaurus/issues/10572

## Upgrade PRs

Example upgrade PRs to look at, including some benchmarks.

Community websites:

- [React Native website](https://github.com/facebook/react-native-website/pull/4268)
- [Babel website](https://github.com/babel/website/pull/2997)
- [Lexical website](https://github.com/facebook/lexical/pull/6761)

Popular plugins:
- [PaloAltoNetworks/docusaurus-openapi-docs - demo website](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/1003)
- [easyops-cn/docusaurus-search-local - demo website](https://github.com/easyops-cn/docusaurus-search-local/pull/468)
- [Redocusaurus - demo website](https://github.com/rohit-gohri/redocusaurus/pull/385)

## Contributing to this issue

We want our community to share feedback on this Docusaurus Faster project.

Please try to adopt it as part of the v3.6+ / canary releases, and tell us how it works for you.

If you encounter problems, please let us know here, and we might create dedicated issues if needed.

This general issue is a great place to follow the Docusaurus Faster project overall, as we try to stabilize it and aim to make it the default for an upcoming major version.