Docusaurus Faster

Open slorber opened this issue 4 months ago • 3 comments

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 issue https://github.com/facebook/docusaurus/issues/4765.

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

We recommend turning them on all at once with siteConfig.future.experimental_faster: true, 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).

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)

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

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.

Oct 04 '24 13:10 slorber

docusaurus docusaurus copied to clipboard