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

> Unlock Docusaurus bundler performance with this guide. Learn to configure Webpack or Rspack using docusaurus.config.js and environment variables for faster builds and optimal site speed.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: performance
- Published: 2026-03-04

---

**Enable Rspack by setting `future.experimental_faster.rspackBundler` to `true` in [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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.

```javascript
// 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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/minification.ts) (lines 26-35) controls parallelism via the `TERSER_PARALLEL` environment variable, allowing you to balance CPU utilization against memory constraints.

```bash

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

```bash

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

export USE_SIMPLE_CSS_MINIFIER=true

```

This flag is inspected in [`minification.ts`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/currentBundler.ts) creates a `rspack-tracing.pftrace` file that can be analyzed at https://ui.perfetto.dev/.

```bash

# 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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) file and ensure `@docusaurus/faster` is installed as a dependency. The [`currentBundler.ts`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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.