# How to Optimize Docusaurus Build Performance and Bundle Size

> Optimize Docusaurus build performance and bundle size with Rspack and SWC. Reduce build times up to 3x and significantly shrink bundles. Learn how to implement these powerful optimizations now.

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

---

**Enable the experimental Rspack bundler via `future.experimental_faster.rspackBundler` in [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-bundler/src/currentBundler.ts). The `getCurrentBundler` function reads your [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-bundler/src/currentBundler.ts).

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

```js
// 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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-bundler/src/minifyHtml.ts), saving memory during the SSG phase.

Example configuration for a CI environment:

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

```bash

# 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](https://ui.perfetto.dev/) to visualize plugin execution times, module resolution delays, and parallelization efficiency.

```bash
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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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.