Speeding Up Docusaurus Builds With Rspack

Docusaurus has a reputation for slow builds on large sites, and it is mostly earned: every page is a React route, every version multiplies the routes, and webpack bundles all of them before the static generation step renders each page. A versioned documentation site with a few thousand pages can take ten minutes to build and need more memory than a standard CI runner has. Docusaurus 3.6 introduced "Docusaurus Faster", which replaces webpack with Rspack, Babel with SWC and the CSS and JS minifiers with faster native ones, behind one configuration flag.

This guide enables it on a 2,100-page product documentation site with three versions, a blog and four custom plugins, fixes the two plugins that broke, and measures build time and memory before and after. It belongs to Docs Frameworks: Docusaurus, Starlight and VitePress, where build time is one of the main points of comparison.

Prerequisites

• Docusaurus 3.6 or later (the site upgraded from 3.5.2 to 3.6.3 first, with no other changes, to measure the baseline on the same version).
• The build passing with no warnings you have been ignoring.
• A CI job that records build duration and peak memory, so the comparison uses the same runner.

Baseline

The 8 GB heap setting was itself a symptom: the build had been failing on the default heap for months, and raising it had pushed the runner into swap on some builds.

Step 1: Install and Enable

npm install @docusaurus/faster@3.6.3

// docusaurus.config.js
export default {
  future: {
    experimental_faster: {
      swcJsLoader: true,
      swcJsMinimizer: true,
      swcHtmlMinimizer: true,
      lightningCssMinimizer: true,
      rspackBundler: true,
      mdxCrossCompilerCache: true,
    },
  },
};

experimental_faster: true turns everything on; listing the options separately makes it easy to bisect if something breaks. mdxCrossCompilerCache compiles each MDX file once and shares the result between the client and server bundles, which on a docs site removes a large amount of duplicate work.

Step 2: Fix the Plugins That Broke

The first build failed in two places.

A custom webpack plugin for build stats. The site's own plugin used compiler.hooks.emit.tapAsync and read compilation.assets to write a JSON summary of chunk sizes. Rspack supports the hook but exposes asset sources differently. The fix was to use the stats API instead — compilation.getStats().toJson({ assets: true }) — which works in both bundlers.

An old SVG loader configured in configureWebpack. It replaced Docusaurus's built-in SVG handling with @svgr/webpack configured by hand, duplicating what Docusaurus already does. Removing the override and using the built-in SVGR support fixed it. Two other configureWebpack customisations — an alias and a DefinePlugin constant — worked unchanged under Rspack.

The configureWebpack hook receives a flag telling you which bundler is active, which helps when a plugin needs different code paths: configureWebpack(config, isServer, { currentBundler }), where currentBundler.name is 'webpack' or 'rspack'.

Step 3: Compare the Output

A faster bundler is only useful if it produces the same site. Both builds were made from the same commit, and compared:

diff <(cd build-webpack && find . -name '*.html' | sort) <(cd build-rspack && find . -name '*.html' | sort)

The file lists were identical: 2,100 pages plus the same 404 and sitemap. Comparing page HTML after stripping hashed asset names showed differences only in script tags and chunk names. Playwright's visual comparison of 60 sampled pages showed no pixel differences above the 0.1% threshold, and the site's end-to-end tests — search, version switching, tabs, the API explorer — passed on both.

Client JavaScript size changed slightly: the main bundle was 3% smaller with SWC's minifier, and total JavaScript across all chunks 1% smaller.

Step 4: Bring the Memory Setting Back Down

With Rspack, peak memory fell to 3.9 GB, so the --max-old-space-size=8192 override was removed. The build now runs on the default heap with headroom, and the runner never swaps. The CI job sets a timeout of 10 minutes, so a regression back towards the old build time fails loudly rather than slowly consuming minutes.

Step 5: Cache Between Builds

Rspack and SWC both benefit from Docusaurus's persistent cache directory (node_modules/.cache). Restoring it in CI keyed on the lockfile and config, with a fallback key, cut warm builds further:

- uses: actions/cache@v4
  with:
    path: node_modules/.cache
    key: docusaurus-${{ hashFiles('package-lock.json', 'docusaurus.config.js') }}-${{ github.sha }}
    restore-keys: docusaurus-${{ hashFiles('package-lock.json', 'docusaurus.config.js') }}-

What Did Not Get Faster

Static generation — rendering each route's HTML — fell from 3 minutes 10 seconds to 1 minute 30 seconds, mostly because the SSG worker pool renders pages in parallel and because less memory pressure meant fewer garbage collection pauses. It is now the largest phase. The remaining time is dominated by the number of routes: three versions of 600 doc pages each. The next improvement on this site is not a bundler change but a content one — dropping the oldest version from the build and serving it as a frozen archive, which would remove about 30% of routes. That is the same trade-off described in Versioned Documentation with Docusaurus.

Local Development

The dev server benefits too, though less dramatically. docusaurus start on the full site took 74 seconds to the first served page with webpack and 21 seconds with Rspack, and hot updates after editing a Markdown file fell from around 2.5 seconds to under a second. Writers who had been starting the dev server with --locale en and a trimmed set of versions to keep startup tolerable went back to running the full site. The one caveat in development is that error overlays for MDX syntax mistakes differ slightly in wording under Rspack; the file and line are still reported.

Measured Impact

Pitfalls & Rollback

• Enabling everything without comparing output. Diff the file list and sample pages visually.
• Plugins that reach into webpack internals. Prefer the stats API and Docusaurus's built-in features.
• Leaving a raised heap setting in place. It hides future memory regressions.
• Unpinned versions. Pin @docusaurus/faster to the same version as @docusaurus/core.
• Rollback: set experimental_faster to false; the rest of the configuration is unchanged, and the build returns to webpack.

Conclusion

Docusaurus Faster attacks the part of a Docusaurus build that grows worst with size — bundling — and on this 2,100-page versioned site it cut a cold build from almost ten minutes to under three and nearly halved peak memory. Two custom build plugins needed small changes, the output was equivalent, and the old bundler remains one flag away.

FAQ

What is Docusaurus Faster?

A set of build-tool replacements available from Docusaurus 3.6 through the @docusaurus/faster package and the future.experimental_faster flag. It swaps webpack for Rspack, Babel for SWC, and Terser and CSSNano for SWC and Lightning CSS minifiers, and enables an SSG worker pool. Each part can be turned on separately.

Will my custom webpack configuration still work with Rspack?

Most of it. Rspack implements the webpack plugin and loader APIs for common cases, so configureWebpack hooks that add aliases, loaders or simple plugins usually work unchanged. Plugins that depend on webpack internals, such as some older bundle analysers or custom compilation hooks, may not. Test each plugin in your configuration after enabling Rspack.

How much faster are Docusaurus builds with Rspack?

On the 2,100-page versioned site in this guide, a cold production build went from 9 minutes 50 seconds to 2 minutes 55 seconds, and peak memory from 7.4 GB to 3.9 GB. Docusaurus reports similar ratios on its own and community sites. Gains are largest on sites with many pages and versions, where bundling dominates build time.

Is it safe to use in production?

The flag is named experimental, but Docusaurus itself and many large sites build with it. Compare the output of both bundlers before switching, keep the old configuration one flag away, and pin the Docusaurus version so a minor upgrade does not change bundler behaviour unexpectedly.

Related

• Parent: Docs Frameworks: Docusaurus, Starlight and VitePress — build time across the frameworks.
• Comparing Docs Framework Build Times — where Docusaurus stood before Rspack.
• Versioned Documentation with Docusaurus — the route count behind long builds.
• Fixing Broken Links Reported by Docusaurus Builds — the checks that run during these builds.
• Measuring Build-Time Regressions in CI — tracking build time after the change.