Build failing with 3.10.0 and faster

[DanRoscigno]

Environment

• Docusaurus 3.10.0
• GitHub Actions runner: ubuntu-24.04-arm, 4 cores, 16 GiB RAM
• NODE_OPTIONS="--max-old-space-size=12288"
• DOCUSAURUS_SSR_CONCURRENCY=8 (effectively 4, capped at core count)
• 7 versions × 3 locales (en, zh, ja)

Config
future: {
v4: true,
faster: true, // original — enables rspackPersistentCache and gitEagerVcs
}

Symptom 1 — zh hangs ~60 minutes then is killed

Last log line before kill:
[PERF] Build > zh > Creating rspack bundler configs - 65.73 ms - (Heap 476mb -> 424mb / Total 550mb)
V8 heap is healthy. Process silently dies ~60 minutes later.

Hypothesis: faster: true enables rspackPersistentCache: true. On CI the .docusaurus dir is not
cached between runs, so rspack compiles everything from scratch and then writes a cold cache —
potentially gigabytes of I/O for 7 versions of zh content — which causes an OOM or I/O hang.

Workaround for Symptom 1:
faster: {
rspackBundler: true,
rspackPersistentCache: !process.env.CI, // GitHub Actions sets CI=true
// ...all other options true
}
This fixed zh. zh built successfully in 308 seconds.

---

Symptom 2 — ja now hangs at the same step

After zh is fixed, ja hangs at:
[PERF] Build > ja > Creating rspack bundler configs - 83.09 ms - (Heap 760mb -> 774mb / Total 883mb)

The V8 heap at this point is 883mb — well within the 12GB ceiling. But this is after en and zh have
already been built in the same process. The rspack Rust native process (memory outside the V8 heap)
appears to have accumulated enough system RAM pressure across three sequential locale builds that
ja's rspack compilation cannot complete. The runner has 16 GiB and the V8 heap reports under 1 GB,
but the process is still killed.

Possible root causes:

• Rspack's Rust allocator does not eagerly return freed memory to the OS between locale builds,
  leaving little headroom for the third locale
• Or rspack spawns threads/workers that consume system RAM independent of the V8 heap

Question for the Docusaurus team: Is there a supported way to limit rspack's native memory usage or
thread count per locale build? And is building multiple locales sequentially in the same process
expected to work within a 16 GiB runner?

---

The navigation concern you raised is worth mentioning too — if the answer is "build locales
separately," how should the top nav (which includes version droppers, locale switchers, etc.) be
handled when each locale's output is built independently?