Why your JavaScript build runs out of memory

Two different failures get described as 'the build ran out of memory', and they need different fixes. Telling them apart takes ten seconds and saves you from applying the wrong one.

# Failure A — V8 hit its own heap ceiling
FATAL ERROR: Reached heap limit Allocation failed -
JavaScript heap out of memory

# Failure B — the kernel killed the process
error Command failed with exit code 137.

Failure A is Node refusing to grow its heap past a configured limit. Failure B is the operating system's OOM killer terminating the process because the machine ran out of physical memory. Exit code 137 is 128 + 9, meaning SIGKILL, and the important detail is that nothing in your Node process gets a chance to report anything — it simply vanishes mid-line.

If you see A, raising the heap limit may help. If you see B, raising the heap limit makes things actively worse, because you're giving V8 permission to allocate more of memory that does not exist.

What is actually consuming gigabytes

Modern frontend builds are memory-hungry in ways that are not obvious from the size of your source tree. A 40,000-line codebase can peak at 6 GB of resident memory during a build, and here's roughly where it goes.

• TypeScript's type checker holds the entire program graph in memory at once. Type inference is not incremental across a fresh build, and heavy generic types — deeply nested conditional types, large union types, ORM schema types generated from a big database — can dominate everything else.
• Bundlers keep module graphs, source maps, and intermediate ASTs live simultaneously. Source map generation in particular roughly doubles peak usage, and it's on by default in most production configs.
• Static site generation runs your page components for every route. Two thousand generated pages means two thousand renders, and any per-render leak compounds across them.
• Parallelism multiplies everything. A build that spawns one worker per CPU core on a 16-core machine runs sixteen copies of the expensive part, each with its own heap.
• Minifiers hold whole chunks in memory to do their work. A single very large vendor chunk is worse than several medium ones.

Measure before you tune

Guessing here wastes days. Get the actual peak first.

# Peak resident set size of the whole build, in KB (GNU time, not the shell builtin)
/usr/bin/time -v npm run build 2>&1 | grep 'Maximum resident'

# On a machine without GNU time, sample it
( while true; do ps -o rss= -p $BUILD_PID; sleep 1; done ) | sort -n | tail -1

# What V8 thinks its ceiling is, on this machine
node -e "console.log(require('v8').getHeapStatistics().heap_size_limit / 1e9, 'GB')"

That last one is worth running on both your laptop and the build machine, because Node sizes its default heap limit from available system memory. Your 32 GB laptop gives V8 a ceiling of around 4 GB; a 2 GB build container gives it a few hundred megabytes. Same code, same Node version, different limit — which is precisely why it builds locally and not in CI.

The fixes, roughly in order of how often they work

Give the build machine more memory

Unglamorous and usually correct. A production build of a mid-sized Next.js or Nuxt application wants 4 GB and is comfortable at 8. Trying to fit it in 2 GB is a fight you can win, but the effort is rarely worth it compared to the cost of the memory for the few minutes a build takes.

This is why PandaStack's app runtime is built on a 4 GB base image rather than something smaller. We started lower and moved up specifically because real Next.js and TypeScript builds were being OOM-killed — the memory is only occupied while the build runs, and being cheap about it just produces confusing failures.

Raise the heap limit — only for failure A

# Applies to Node processes spawned by the build too, unlike a bare node flag
NODE_OPTIONS=--max-old-space-size=6144 npm run build

Set it below your actual available memory, not above. Setting 8192 on a 4 GB machine converts a clean V8 error into an opaque SIGKILL — you have traded a message that tells you what happened for one that doesn't.

Turn down parallelism

Counter-intuitive, and frequently the fix on constrained machines. If your build spawns a worker per core, capping workers cuts peak memory almost proportionally at a modest cost in wall-clock time.

// next.config.js
module.exports = {
  experimental: { cpus: 2 },        // cap build workers
  productionBrowserSourceMaps: false, // large, and rarely wanted in prod
};

// tsconfig.json — skip type-checking of node_modules .d.ts files
{ "compilerOptions": { "skipLibCheck": true, "incremental": true } }

`skipLibCheck` is the single highest-leverage TypeScript flag here. Type-checking every declaration file in `node_modules` costs a lot of memory to find approximately zero bugs in your own code.

Split the type check out of the build

If the bundler and the type checker both run in one process, their peaks stack. Running them as separate sequential commands means each gets the whole machine, one at a time.

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "build": "next build",
    "ci": "npm run typecheck && npm run build"
  }
}

This also gives you a better failure signal: you learn immediately whether the problem is types or bundling, rather than watching one process die with both possibilities open.

When it's a genuine regression

If a build that used to fit suddenly doesn't, don't reach for flags — find the change. The usual culprits, in the order I'd check them:

1. A generated types file that grew enormously. ORM clients generated from a large schema produce very large union and conditional types, and adding tables can make checking them superlinearly more expensive.
2. A newly imported library with no tree-shaking, pulling a huge dependency graph into every chunk.
3. A `barrel` index file that re-exports everything, defeating tree-shaking across the whole module graph.
4. Route count growth in static generation — going from 200 to 5,000 pre-rendered pages changes the shape of the build entirely.
5. A dependency upgrade. Bundler and framework major versions do change memory characteristics, sometimes substantially.

Bisecting is genuinely effective here because the signal is loud: the build either fits or it doesn't. A handful of runs across a range of commits will find the change that did it, and the fix is usually a five-line diff rather than an infrastructure decision.

The general shape: read the error carefully enough to know whether V8 or the kernel killed you, measure the actual peak rather than estimating it, and give the build the memory it needs instead of squeezing it into a container sized for the running app. A build's memory profile has almost nothing to do with the memory your app needs to serve requests, and sizing them together is the underlying mistake.