docusaurus build OOM "JavaScript heap out of memory" large site
Fixes Docusaurus builds that run out of JavaScript heap memory on large sites. Use when the build crashes with heap out of memory. Not for locale or routing errors.
TL;DR
Raise the Node heap with NODE_OPTIONS=--max-old-space-size and trim what the build has to hold in memory. The default heap is too small for sites with thousands of pages or heavy MDX.
Error
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memorySteps
- Confirm it is heap exhaustion and not a leak in one page: the error above during the bundle or render phase on a large site. Expected: the crash message matches heap limit, not a syntax error.
- Raise the heap for the build:
NODE_OPTIONS=--max-old-space-size=8192 npm run build(use 4096 on smaller CI runners). Expected: the build gets past the previous crash point. - Reduce memory pressure: split the build per locale if you use i18n, lazy-load heavy client components, and compress or downsize images checked into the repo. Expected: peak memory drops measurably.
- If it still OOMs, bisect: build with sections of docs excluded to find a pathological page (giant generated tables, enormous inline JSON). Expected: one page or plugin identified as the hog.
When to use
- The build dies with "JavaScript heap out of memory"
- The site has thousands of pages or very large generated docs
- A docs agent generated huge pages (full API dumps in one file)
When not to use
- The build fails with a normal error message (not memory-related)
- The OOM happens in dev server watch mode (different tuning)
- The machine itself is out of RAM (check system memory first)
Tool compatibility
Docusaurus 2.x and 3.x on Node 18+. The NODE_OPTIONS flag works on any Node version.
Variant phrasings
OOM only in CI, not locally
CI runners have less RAM. Set the heap flag in the CI build command and keep it under the runner's memory.
heap error during the search index step
A huge search index (thousands of pages with full text) can OOM the indexer. Exclude generated reference pages from indexing or raise the heap.
Why it happens
Static generation renders every page in one Node process, and MDX compilation plus webpack bundling hold the whole site graph in memory. Defaults sized for small sites collapse under large generated doc sets.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_7zuYXo9CNUyQ-Qwwf-ffFA