Storybook build "JavaScript heap out of memory" in CI

A large Storybook (many stories, heavy addons, source maps) can exceed Node's default heap during the production build. The process is killed with a V8 heap allocation failure. Raising --max-old-space-size gives it room.

What this error means

The build dies with "FATAL ERROR: ... JavaScript heap out of memory" or the step exits 137 (OOM-killed) during storybook build.

storybook

<--- Last few GCs --->
FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed -
JavaScript heap out of memory

Common causes

The build exceeds Node's default heap

A big story set plus source maps and addons pushes memory past the default limit, and V8 aborts.

The runner has less memory than the local machine

The build fits locally but the CI runner has a smaller RAM ceiling, so the same build is OOM-killed.

How to fix it

Raise the Node heap for the build step

Set NODE_OPTIONS with a larger --max-old-space-size for the build.
Keep it below the runner's physical RAM to avoid the OS killing the process.
Re-run the build.

.github/workflows/ci.yml

- name: Build Storybook
  run: npm run build-storybook
  env:
    NODE_OPTIONS: --max-old-space-size=4096

Reduce build memory pressure

Disable source maps for the CI build or split very large story sets so peak memory drops.

.storybook/main.ts

// .storybook/main.ts
export default {
  typescript: { reactDocgen: false },
};

How to prevent it

Set NODE_OPTIONS=--max-old-space-size for large Storybook builds in CI.
Use a runner with enough RAM for the build's peak usage.
Trim heavy addons or docgen when they are not needed for the build.