How to Configure Docusaurus Bundler (Webpack/Rspack) for Optimal Performance

Enable Rspack by setting future.experimental_faster.rspackBundler to true in docusaurus.config.js, then tune minimizers via environment variables like TERSER_PARALLEL and USE_SIMPLE_CSS_MINIFIER for maximum build speed.

The facebook/docusaurus repository abstracts its build system behind the @docusaurus/bundler package, providing a unified interface to configure Docusaurus bundler behavior for either Webpack or Rspack. By leveraging the experimental Faster architecture and specific environment variables, you can significantly reduce build times while maintaining compatible output bundles.

Select Your Bundler Architecture

Docusaurus supports seamless switching between Webpack (the historic default) and Rspack (the Rust-based successor) through a single configuration flag.

Enable Rspack for Modern Build Performance

To switch bundlers, set the rspackBundler flag in your site configuration. The logic in packages/docusaurus-bundler/src/currentBundler.ts reads this value and returns the appropriate implementation, loading Rspack plugins such as SwcJsMinimizerRspackPlugin and LightningCssMinimizerRspackPlugin instead of their Webpack equivalents.

// docusaurus.config.js
module.exports = {
  future: {
    experimental_faster: {
      // Switches the bundler to Rspack for faster builds
      // Requires @docusaurus/faster as a dependency
      rspackBundler: true,
    },
  },
};

When enabled, currentBundler.ts dynamically imports the Rspack compiler and registers native minimizers that avoid the overhead of JavaScript-based plugins.

Tune Minification Strategies

Performance tuning extends beyond bundler selection into how JavaScript and CSS are compressed. The packages/docusaurus-bundler/src/minification.ts file centralizes this logic, selecting minimizers based on your chosen bundler and environment variables.

Optimize JavaScript Compression with Terser

For Webpack builds, Docusaurus uses terser-webpack-plugin for JavaScript minification. The getTerserParallel function in minification.ts (lines 26-35) controls parallelism via the TERSER_PARALLEL environment variable, allowing you to balance CPU utilization against memory constraints.

# Use all available CPU cores (default behavior)

export TERSER_PARALLEL=true

# Limit to 4 parallel workers to reduce memory pressure

export TERSER_PARALLEL=4

# Disable parallelism entirely for low-memory environments

export TERSER_PARALLEL=false

These values are passed directly to new TerserPlugin({ parallel, ... }) in the minimizer configuration.

Choose Lightweight CSS Minification

By default, Docusaurus employs an advanced pipeline using CssNano and CleanCSS. When this pipeline becomes a bottleneck, you can fall back to the basic CssMinimizerPlugin by setting USE_SIMPLE_CSS_MINIFIER.

# Bypass CssNano+CleanCSS for faster but less aggressive CSS compression

export USE_SIMPLE_CSS_MINIFIER=true

This flag is inspected in minification.ts (lines 88-94) and forces the lightweight minimization path. When using Rspack, the bundler automatically swaps to LightningCssMinimizerRspackPlugin, which provides native-speed CSS processing without additional configuration.

Reduce Cold Start Overhead

The @docusaurus/bundler package minimizes startup time through strategic lazy loading. The packages/docusaurus-bundler/src/importFaster.ts module dynamically imports heavy dependencies—Rspack itself, the Swc loader, browserslist queries, and LightningCSS options—only when the experimental Faster features are enabled.

This architecture ensures that sites using the legacy Webpack path do not pay the memory and initialization cost of loading Rspack or Swc modules until they are explicitly requested via configuration.

Profile and Debug Build Performance

For deep performance analysis, Docusaurus supports Rspack-specific tracing that generates Perfetto-compatible profiles.

Enable Rspack Tracing

Set the DOCUSAURUS_RSPACK_TRACE environment variable to activate detailed tracing. The registerBundlerTracing function in currentBundler.ts creates a rspack-tracing.pftrace file that can be analyzed at https://ui.perfetto.dev/.

# Generate a detailed trace file for profiling

export DOCUSAURUS_RSPACK_TRACE=info

# Or use "true" for the default trace set

docusaurus build

This instrumentation helps identify slow loaders or plugins without modifying the underlying source code.

Implementation Reference

Understanding the key source files helps you trace configuration values through the build pipeline:

• packages/docusaurus-bundler/src/currentBundler.ts – Detects the selected bundler and loads appropriate plugins (CSS extract, copy, progress bar, and tracing).
• packages/docusaurus-bundler/src/compiler.ts – Wraps the bundler’s run API, formats errors, and manages the compile lifecycle including proper shutdown for persistent caching.
• packages/docusaurus-bundler/src/minification.ts – Contains getMinimizers and getTerserParallel, selecting JavaScript and CSS minimizers based on Faster options and environment variables.
• packages/docusaurus-bundler/src/importFaster.ts – Lazily imports @docusaurus/faster and re-exports helpers for Rspack, Swc, browserslist, and LightningCSS.

When docusaurus build executes, the CLI creates Webpack/Rspack configuration objects and invokes compile from compiler.ts, which constructs the bundler instance and injects minimizers via getMinimizers before running the compilation.

Summary

• Enable Rspack by setting future.experimental_faster.rspackBundler: true in docusaurus.config.js to use the modern Rust-based compiler.
• Control Terser parallelism with the TERSER_PARALLEL environment variable to optimize CPU usage during JavaScript minification.
• Simplify CSS minification using USE_SIMPLE_CSS_MINIFIER=true when the default CssNano pipeline creates bottlenecks.
• Profile builds by setting DOCUSAURUS_RSPACK_TRACE=info to generate Perfetto trace files for analysis.
• Leverage lazy loading via importFaster.ts to keep initial startup fast, loading heavy dependencies only when experimental features are active.

Frequently Asked Questions

How do I switch from Webpack to Rspack in Docusaurus?

Add rspackBundler: true to the future.experimental_faster object in your docusaurus.config.js file and ensure @docusaurus/faster is installed as a dependency. The currentBundler.ts module automatically detects this flag and returns the Rspack implementation instead of Webpack.

What does the TERSER_PARALLEL environment variable control?

TERSER_PARALLEL determines the number of parallel workers used by Terser for JavaScript minification in Webpack builds. Set it to true for auto-detection, a specific number like 4 to limit workers, or false to disable parallelism and reduce memory consumption.

When should I enable USE_SIMPLE_CSS_MINIFIER?

Enable USE_SIMPLE_CSS_MINIFIER=true when the default CssNano and CleanCSS pipeline consumes excessive build time or memory. This environment variable forces the bundler to use the basic CssMinimizerPlugin, trading marginal compression efficiency for significantly faster processing.

How can I trace Rspack performance bottlenecks?

Set DOCUSAURUS_RSPACK_TRACE=info before running docusaurus build. The registerBundlerTracing function in currentBundler.ts generates a rspack-tracing.pftrace file that you can upload to https://ui.perfetto.dev/ to visualize loader timings, plugin execution, and other performance metrics.

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