Docusaurus Faster

[slorber]

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 #4765.

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: Use SWC to transpile JS (instead of Babel).
• swcJsMinimizer: Use SWC to minify JS (instead of Terser).
• swcHtmlMinimizer : Use SWC to minify HTML and inlined JS/CSS (instead of html-minifier-terser).
• lightningCssMinimizer: Use Lightning CSS to minify CSS (instead of cssnano and clean-css).
• rspackBundler: Use Rspack to bundle your app (instead of webpack).
• mdxCrossCompilerCache: Compile MDX files only once for both browser/Node.js environments instead of twice.
• ssgWorkerThreads (🆕 v3.8+): Uses a Node.js Worker thread pool to optimize CPU usage during SSG.
• rspackPersistentCache (🆕 v3.8+): Uses Rspack Persistent Cache to rebuild your site much faster.

#10931

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 feature flag on, because some Docusaurus Faster options rely on upcoming changes.

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

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)
• 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: #10572

Upgrade PRs

Example upgrade PRs to look at, including some benchmarks.

Community websites:

• React Native website
• Babel website
• Lexical website

Popular plugins:

• PaloAltoNetworks/docusaurus-openapi-docs - demo website
• easyops-cn/docusaurus-search-local - demo website
• Redocusaurus - demo website

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.

[sserrata]

Thanks @slorber, sharing comparison results for our OpenAPI plugin site.

Cold Build No Optimization

[PERF] Build > en > Bundling with webpack - 41.58 seconds!
[PERF] Build > en > SSG > Load App renderer > Load server bundle - 8.49 ms
[PERF] Build > en > SSG > Load App renderer > Server bundle size = 17.241 MB
[PERF] Build > en > SSG > Load App renderer > Evaluate server bundle - 225.13 ms
[PERF] Build > en > SSG > Load App renderer - 234.15 ms
[PERF] Build > en > SSG > Generate static files - 3.26 seconds!
[PERF] Build > en > SSG - 3.50 seconds!
[PERF] Build > en > postBuild() - 10.58 ms
[PERF] Build > en > Broken links checker - 28.01 ms
[SUCCESS] Generated static files in "build".
[PERF] Build > en - 46.38 seconds!
[PERF] Build - 46.38 seconds!
[INFO] Use `npm run serve` command to test your build locally.
✨  Done in 51.97s.

Cold Build With Experimental Faster Enabled

[PERF] Build > en > Bundling with webpack - 23.44 seconds!
[PERF] Build > en > SSG > Load App renderer > Load server bundle - 7.16 ms
[PERF] Build > en > SSG > Load App renderer > Server bundle size = 17.767 MB
[PERF] Build > en > SSG > Load App renderer > Evaluate server bundle - 222.76 ms
[PERF] Build > en > SSG > Load App renderer - 230.31 ms
[PERF] Build > en > SSG > Generate static files - 1.82 seconds!
[PERF] Build > en > SSG - 2.06 seconds!
[PERF] Build > en > postBuild() - 9.49 ms
[PERF] Build > en > Broken links checker - 27.01 ms
[SUCCESS] Generated static files in "build".
[PERF] Build > en - 26.79 seconds!
[PERF] Build - 26.79 seconds!
[INFO] Use `npm run serve` command to test your build locally.
✨  Done in 32.52s.

---

Edit from @slorber: results above are still based on Webpack.

See PaloAltoNetworks/docusaurus-openapi-docs#1003 for the real upgrade.

Benchmark shows demo site building:

• 2.7x faster on cold builds
• 1.2x slower (for now) on warn builds

[slorber]

Thanks for reporting these early results @sserrata

Note that the Rspack PR hasn't been merged yet and if you use canary today you are still using Webpack.

For plugin authors, it's possible that Rspack will not work immediately out of the box. Some plugins will have to adjust their code to add Rspack support, eventually requiring a minimum version of Docusaurus v3.6+ to do so.

Follow this issue to know when a guide for plugin authors is ready: #10572

[slorber]

The Rspack support has been merged: #10402

You can try canary 0.0.0-6101 or above to benefit from all the upcoming perf improvements.

Here's an example PR upgrading the React Native website: facebook/react-native-website#4268

How to benchmark

One way to benchmark this is to use hyperfine with an env variable:

const config = {
  future: {
    experimental_faster: (process.env.DOCUSAURUS_FASTER ?? 'true') === 'true',
  },
}

For cold builds:

hyperfine --prepare 'yarn clear' --runs 5 'DOCUSAURUS_FASTER=false yarn build' 'DOCUSAURUS_FASTER=true yarn build'

For warm rebuilds:

DOCUSAURUS_FASTER=false yarn build
hyperfine --runs 5 'DOCUSAURUS_FASTER=false yarn build' 'DOCUSAURUS_FASTER=true yarn build'

Troubleshooting slow builds

It's possible that enabling this new option does not give you the expected speed increase.

Perf logger

You can get a more verbose performance logger with the DOCUSAURUS_PERF_LOGGER=true env variable, giving you the time it takes to execute each step:

Rsdoctor

Another option is to use Rsdoctor, which works for both webpack and Rspack.

It can tell you which loader/plugin/phase is slow while bundling your app.

For many Docusaurus sites (including ours), the slow loaders are postcss/css-loader, mdx loader, and the image loaders of our ideal image plugin. Despite these slow loaders, Docusaurus Faster builds 3x faster.

It is possible that a Docusaurus plugin you use slows down your build. Rsdoctor might be able to give you insight on that.

We'll probably release an official Rsdoctor plugin for Docusaurus, but in the meantime here's a Docusaurus plugin we built to integrate it into our own site: https://github.com/facebook/docusaurus/blob/main/website/src/plugins/rsdoctor/RsdoctorPlugin.ts