[Bug]: Rspack persistent cache does not emit all assets

[slorber]

System Info

npx envinfo --system --npmPackages '@rspack/*' --binaries --browsers

  System:
    OS: macOS 15.5
    CPU: (12) arm64 Apple M3 Pro
    Memory: 5.37 GB / 36.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 24.0.1 - ~/Library/Caches/fnm_multishells/41079_1749137597413/bin/node
    Yarn: 1.22.22 - ~/Library/Caches/fnm_multishells/41079_1749137597413/bin/yarn
    npm: 11.3.0 - ~/Library/Caches/fnm_multishells/41079_1749137597413/bin/npm
    bun: 1.1.45 - ~/.bun/bin/bun
  Browsers:
    Brave Browser: 135.1.77.100
    Chrome: 137.0.7151.69
    Chrome Canary: 139.0.7221.0
    Firefox Nightly: 141.0a1
    Safari: 18.5
    Safari Technology Preview: 18.4

Details

We have a really weird persistent cache bug affecting Docusaurus on Rspack 1.3.5 (but it also happens for older versions like 1.3.0).

In some particular cases, the bundler assets (CSS, JS) are not emitted or contain unexpected content.

This doesn't happen randomly: I can consistently reproduce on both our prod CI and locally.

The particular situation I can reproduce is Docusaurus builds on localized sites. When running multiple builds, the localized sites will build incorrectly.

To give a better understanding of the Docusaurus bundling configuration:

• We use a multi-compiler with client/server config
• Localized builds will build one localized site at a time, sequentially, in the same process. Each locale uses a different cache name

For example, the following Docusaurus website command: yarn build:website:fast --locale en --locale fr

Will bundle the app with a flow similar to this:

async function buildSite(locale) {

  const configs = [
    {
      name: "client"
      experiments: {cache: {
        type: 'filesystem',
        version: `client-${locale}`
      }}
    },  
    {
      name: "server"
      experiments: {cache: {
        type: 'filesystem',
        version: `server-${locale}`
      }}
    },    
  ]
  
  // Note: compile is our util and just wraps rspack(configs).run() in Promise
  await compile(configs);
  
  // Run SSG
}

await buildSite("en");
await buildSite("fr");

On the first run (cold caches), this works perfectly fine.

On the subsequent runs (warm caches, 4 folders in .cache/.rspack), the French site will have missing/buggy assets.

Surprisingly, this only happens when the subsequent runs happen in a new process triggered by a new CLI call.

I cannot reproduce the problem within the same process.

Compiling twice the configs in a row didn't reproduce the problem:

await compile(configs);
await compile(configs);

Building twice the localized sites in a row didn't reproduce the problem:

await buildSite("en");
await buildSite("fr");
await buildSite("en");
await buildSite("fr");
await buildSite("fr");
await buildSite("fr");
await buildSite("fr");

I suspect this is related to reading the persistent cache from disk instead of using what's in memory, but not sure how to troubleshoot such problem.

The problem immediately disappears when clearing the cache, or removing the persistent cache config, or using Webpack.

Changing/removing configs we use for incremental, parallelCodeSplitting, optimization.concatenateModules, or optimization.mergeDuplicateChunks doesn't seem to fix the problem. Disabling minification neither.

---

Reproduce Steps

Here are steps that reproduce consistently, both locally and in our CI

Initial setup:

git clone git@github.com:facebook/docusaurus.git

cd docusaurus

# Optional, checkout specific repro commit using latest Rspack 1.3.15 (but it should also repro on "main" anyway)
git checkout 315e3f617e38f7d99fe0ba3b253d1eb450b6aaba

yarn install

# Clear all caches, including ./node_modules/.rspack
yarn clear:website

Repro:

# First run: works fine for both localized sites
# English site works fine: http://localhost:3000/
# French site works fine: http://localhost:3000/fr
yarn build:website:fast --locale en --locale fr && yarn serve:website

# Second run
# English site works fine: http://localhost:3000/
# French site did not emit any CSS file in build/fr/assets/css, see http://localhost:3000/fr
yarn build:website:fast --locale en --locale fr && yarn serve:website

# Third run
# English site works fine: http://localhost:3000/
# French site did not emit proper build/fr/__server/server.bundle.js (the file exists, but its content looks unexpected, and code splitter chunks in __server/assets/js are also missing)
# French SSG fails with error: Docusaurus Bug: server bundle export from "server.bundle.js" must be a function that renders the Docusaurus React app, not undefined
# Surprisingly, the CSS file is back in build/fr/assets/css
yarn build:website:fast --locale en --locale fr && yarn serve:website

The Rspack persistent cache can be disabled in website/docusaurus.config.ts

The bundler config can be modified in packages/docusaurus/src/webpack/base.ts (run yarn watch in another terminal if you modify any TS source)

---

This can also be reproduced on a newly initialized Docusaurus site (although it might be less convenient to tweak it through node_modules:

npx create-docusaurus@latest my-website classic --typescript

cd my-website

yarn add @docusaurus/faster

Add this in the config file manually:

  future: {
    v4: true,
    experimental_faster: true,
  },

Repro:

yarn clear
yarn build --locale en --locale fr
yarn build --locale en --locale fr
yarn serve

French site is broken at http://localhost:3000/fr

[jerrykingxyz]

@slorber Thanks for the detailed report. This bug is a known issue caused by rspack auto-increment ID(such as DependencyID). Multiple compilers on the same thread will share the id generator, which will indirectly affect other compilers when the persistent cache restores it.

I will fix it as soon as possible.

[slorber]

Great, I can confirm my bug is fixed in v1.4 🥳