How to Optimize Docusaurus Build Performance and Bundle Size

Enable the experimental Rspack bundler via future.experimental_faster.rspackBundler in docusaurus.config.js and configure SWC minification to reduce build times by up to 3× and significantly decrease bundle size.

Docusaurus v3 introduces a bundler abstraction layer in packages/docusaurus-bundler that supports both Webpack and the Rust-based Rspack. Learning how to optimize Docusaurus build performance and bundle size centers on selecting the faster bundler, tuning the minification pipeline in packages/docusaurus-bundler/src/minification.ts, and configuring parallel SSG workers for maximum throughput.

Switch from Webpack to Rspack

Docusaurus selects the active bundler in packages/docusaurus-bundler/src/currentBundler.ts. The getCurrentBundler function reads your docusaurus.config.js and returns either a Webpack or Rspack instance based on the future.experimental_faster.rspackBundler flag.

Webpack (default) relies on Terser and CSS-Minimizer, requires manual filesystem cache configuration, and processes modules sequentially unless explicitly parallelized.

Rspack (experimental) enables parallel code splitting by default, provides built-in persistent caching that automatically survives across builds, and leverages native Rust-based tooling (SWC and LightningCSS) to deliver up to 2–3× faster SSG builds according to the implementation in packages/docusaurus-bundler/src/currentBundler.ts.

To enable Rspack, add the following to your configuration file:

// docusaurus.config.js
module.exports = {
  future: {
    experimental_faster: {
      rspackBundler: true,
    },
  },
};

Configure the Minification Pipeline

The minification strategy is centralized in packages/docusaurus-bundler/src/minification.ts. The getMinimizers factory function dynamically selects JavaScript and CSS minifiers based on your faster configuration object.

JavaScript Minification with SWC

The getJsMinimizer function chooses between terser-webpack-plugin (default for Webpack) and SWC minification via TerserPlugin.swcMinify. When using Rspack or explicitly setting swcJsMinimizer: true, Docusaurus replaces the JavaScript minifier with the high-performance SWC Rust compiler, drastically reducing minification time for large codebases.

CSS Optimization with LightningCSS

The getCssMinimizer function selects either CssNano (Webpack default) or LightningCSS (Rspack default). LightningCSS is a native CSS parser and minifier that runs significantly faster than the JavaScript-based CssNano alternative. To force LightningCSS even in custom configurations, ensure lightningCssMinimizer: true is set in your experimental_faster flags.

Fine-Tune with Environment Variables

Docusaurus exposes several environment variables to control minifier behavior without modifying source code:

• TERSER_PARALLEL – Controls Terser worker parallelism. Set to false to disable parallel processing, or specify an integer (e.g., 4) to limit worker threads.
• USE_SIMPLE_CSS_MINIFIER – Set to true to bypass the advanced CssNano configuration and use the default CssMinimizerPlugin, reducing CPU overhead on resource-constrained environments.
• SKIP_HTML_MINIFICATION – Set to true to disable the HTML minifier implemented in packages/docusaurus-bundler/src/minifyHtml.ts, saving memory during the SSG phase.

Example configuration for a CI environment:

export TERSER_PARALLEL=4
export USE_SIMPLE_CSS_MINIFIER=true
export SKIP_HTML_MINIFICATION=true
yarn build

Optimize SSG Worker Threads

Docusaurus 3.0 introduced parallel SSG worker pooling via the docusaurus-faster package. The pool size automatically scales with your CPU count, but you can constrain memory usage per worker to prevent out-of-memory errors on shared CI agents. Set DOCUSAURUS_SSG_WORKER_THREAD_RECYCLER_MAX_MEMORY (introduced in PR #11166) to limit each worker’s heap size in megabytes.

# Limit each worker to 512 MB (useful for low-RAM containers)

export DOCUSAURUS_SSG_WORKER_THREAD_RECYCLER_MAX_MEMORY=512
yarn build

Profile Build Performance with Bundler Tracing

To diagnose bottlenecks in the bundling phase, enable the built-in tracing system. Set DOCUSAURUS_RSPACK_TRACE=true to generate a rspack-tracing.pftrace file in your project root after the build completes. Load this file into Perfetto UI to visualize plugin execution times, module resolution delays, and parallelization efficiency.

export DOCUSAURUS_RSPACK_TRACE=true
yarn build

# Analyze ./rspack-tracing.pftrace

Remove Legacy Webpack Anti-Patterns

Recent Docusaurus versions removed specific Webpack optimizations that historically degraded performance. According to the repository changelog and source history:

• optimization.removeAvailableModules – Removed in PR #11072 because it forced Webpack to traverse the entire module graph, increasing compilation time.
• clean-webpack-plugin – Removed in PR #11037 to eliminate unnecessary file system operations between builds.

If you maintain a custom Webpack configuration in docusaurus.config.js, verify that you do not manually re-enable these options, as they directly counteract performance improvements in the current bundler abstraction.

Summary

• Switch to Rspack – Set future.experimental_faster.rspackBundler: true in docusaurus.config.js to enable the Rust-based bundler with built-in persistent caching.
• Enable native minifiers – Configure swcJsMinimizer: true and lightningCssMinimizer: true to leverage Rust-based SWC and LightningCSS for faster JS and CSS optimization.
• Control resource usage – Tune TERSER_PARALLEL and DOCUSAURUS_SSG_WORKER_THREAD_RECYCLER_MAX_MEMORY to prevent out-of-memory errors on CI systems.
• Profile bottlenecks – Use DOCUSAURUS_RSPACK_TRACE=true to generate Perfetto traces and identify slow plugins or loaders.
• Avoid legacy settings – Do not enable optimization.removeAvailableModules or clean-webpack-plugin in custom Webpack configurations, as these were intentionally removed to improve performance.

Frequently Asked Questions

Is Rspack stable enough for production Docusaurus sites?

Rspack is currently marked as experimental in packages/docusaurus-bundler/src/currentBundler.ts, but it is actively maintained and achieves 2–3× faster builds than Webpack. For production documentation sites, test the Rspack build thoroughly with your specific plugin ecosystem, as third-party Docusaurus plugins may have Webpack-specific assumptions that require updates.

How do I fix out-of-memory errors during the static site generation phase?

Reduce the memory footprint per SSG worker by setting DOCUSAURUS_SSG_WORKER_THREAD_RECYCLER_MAX_MEMORY to a lower value (e.g., 512 for 512 MB), or disable HTML minification entirely with SKIP_HTML_MINIFICATION=true. These adjustments minimize heap usage during the parallel rendering of pages implemented in the docusaurus-faster package.

Can I use SWC minification with the default Webpack bundler?

Yes. While Rspack defaults to SWC, you can enable future.experimental_faster.swcJsMinimizer: true while keeping rspackBundler: false to force the getJsMinimizer function in packages/docusaurus-bundler/src/minification.ts to use SWC instead of Terser, even under Webpack. Note that LightningCSS requires Rspack and cannot be used with Webpack.

What is the fastest configuration for CI/CD pipelines?

For optimal CI performance, enable Rspack with rspackBundler: true, set TERSER_PARALLEL to match your container’s CPU limit (often 2 or 4 cores), and cap worker memory with DOCUSAURUS_SSG_WORKER_THREAD_RECYCLER_MAX_MEMORY. Additionally, enable persistent caching in your CI environment to allow Rspack to reuse compiled modules across builds, dramatically reducing cold-start times.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}