Reducing the app buildling time with concatenateModules: false

[slorber]

Docusaurus uses Webpack/Rspack to bundle your app, which by default uses optimization.concatenateModules: true for production builds.

While working on Docusaurus v3.8 optimizations, we found out that this optimization:

• can be very expensive on very large sites (see benchmarks on a 11k docs website)
• only saves 3% of JS of the total JS assets size

If you have a very large site, and build time is a concern, you have the option to make builds faster, at the cost of slightly increased JS size.

A good idea could be to disable this optimization for local and deploy preview builds, but keep it only for production deployments.

Here's an example of how to do this when deploying on Vercel or Netlify:

// See https://vercel.com/docs/environment-variables/system-environment-variables
const isVercelProductionDeployment = process.env.VERCEL && process.env.VERCEL_ENV === "production"

// See https://docs.netlify.com/configure-builds/environment-variables/
const isNetlifyProductionDeployment = process.env.NETLIFY && process.env.CONTEXT === "production";

const isProductionDeployment = isVercelProductionDeployment || isNetlifyProductionDeployment; 

// Site config
const siteConfig = {
  // ... other site config
  plugins: [
    function disableExpensiveBundlerOptimizationPlugin() {
      return {
        name: "disable-expensive-bundler-optimizations",
        configureWebpack(_config, isServer) {
          return {
            optimization: {
              concatenateModules: isProductionDeployment ? !isServer : false,
            },
          };
        },
      };
    },
  ],
};

---

Why not apply this by default?

By default, we believe it's better to favor UX (saving 3% JS for your site's visitors) rather than DX (reducing build times).

If you have a different opinion, it should be your responsibility to configure your optimizations accordingly. A good compromise is to only optimize for production deployment. Unfortunately, Docusaurus can't know if your docusaurus build is run for a test / deploy preview environment, or your real production deployment.

Also, the Rspack team is aware of a possible bottleneck on this optimization that doesn't scale well when the number of docs increases. They will likely improve things in the future, making this trick less impactful. We could make this easier to configure, but we also don't want to introduce a first-party config option that we'll likely remove later.

---

Share your results

Please share below how much this tip improved your build time; this may help other users decide if they should try it too!

You can use DOCUSAURUS_PERF_LOGGER=true to print additional logs and know how much time it takes to bundle your app.

I'll start with these results from a very large 11k docs website:

Before:

• Cold build, optimization enabled: 660s
• Warn build, optimization enabled: 550s

After:

• Cold build, optimization disabled: 170s 🔥
• Warn build, optimization disabled: 33s 🔥

[felipecrs]

@slorber I believe you can consider disabling these optimizations by default when not building for production. There's no risk in that, is there? A Docusaurus dev build is already very different than a production build.

PS: toggling this option made no difference in my build time, which remains around 20s after all 3.8 enhancements.

[slorber]

@slorber I believe you can consider disabling these optimizations by default when not building for production. There's no risk in that, is there? A Docusaurus dev build is already very different than a production build.

I'll have to check, but I believe we use mode: 'development' for docusaurus start and docusaurus build --dev, so the optimization is likely off in these cases. Eventually, I'll move the explicit config to the server config only so that it never affects client configs (including docusaurus start, but on the large site above I didn't really see a bottleneck so I'm not sure it's used by the dev server anyway.

PS: toggling this option made no difference in my build time, which remains around 20s after all 3.8 enhancements.

This option is unlikely to have a significant impact on small sites, because the problem is related to algorithmic complexity, and becomes more significant as the number of pages/js modules increases.

The site above is very large (11k docs), and the algorithm doesn't scale well as the number of pages increases. If your site builds in 20s, it's probably not large enough to be impacted by this perf bottleneck.

On our website (~1200 pages) and ReactNative.dev (~1950 pages,) we still see a very visible improvement.

See React Native website PR and the impact of this optimization removal here: facebook/react-native-website#4607

Default:

• Cold build: 37s
• Warm rebuild: 17s

With the expensive optimization disabled:

• Cold build: 19s
• Warm rebuild: 3s

[felipecrs]

Wow. This difference in the React Native website is crazy big. Definitely something worth trying, and to have in mind. Thank you!