Lorixen.
EN

'JavaScript heap out of memory' in your build? Fix it properly

Short answer: Builds for modern websites and apps run in Node.js, and Node's JavaScript heap has a size limit. A large project, source maps, type checking and parallel build workers can exceed it, and the build dies with "Reached heap limit" or "JavaScript heap out of memory". You can raise the limit with NODE_OPTIONS=--max-old-space-size=…, but only up to the memory the machine actually has, leaving room for everything else. The lasting fixes are building on a machine with enough memory, usually CI rather than the production server, and reducing what the build holds in memory at once.

What the error means

Node.js runs JavaScript with the V8 engine, which keeps most objects in a part of memory called the old space. When it approaches its limit, Node's documentation explains, V8 spends more and more time on garbage collection trying to free memory; when that fails, the process crashes. Build tools such as bundlers, compilers and static site generators can hold an enormous amount in memory: every module, its source map, type information and the output.

Typical triggers:

  • the project grew: more pages, more dependencies, bigger images processed at build time
  • source maps for production builds
  • type checking running inside the build
  • a bundler using several worker processes in parallel
  • building on a small server alongside the running site and database

Raising the limit (carefully)

Node's documentation describes --max-old-space-size=SIZE, in MiB, to set the limit, and gives a useful rule of thumb: on a machine with 2 GiB of memory, consider about 1536 (1.5 GiB) to leave memory for other uses and avoid swapping.

Because builds are usually started by a tool, pass it through the NODE_OPTIONS environment variable, which Node reads before command-line options and which allows this particular flag:

NODE_OPTIONS=--max-old-space-size=4096 npm run build

Recent Node versions also offer --max-old-space-size-percentage, which sets the limit as a percentage of available system memory and takes precedence if both are set. That's handy when the same build runs on machines of different sizes.

Don't set the limit above the machine's real memory. The build then pushes the system into swap or gets killed by the operating system instead, which is slower and more confusing.

Know how much memory you actually have

  • CI runners. GitHub's reference for its hosted runners lists 16 GB of memory for the standard Linux runner on public repositories and 8 GB on private ones, with smaller "slim" runners at 5 GB. Other CI services publish similar tables. If your build needs more, you can choose larger runners.
  • Small VPS. A 1 or 2 GB server running the website, a database and a build at the same time is the most common place this error appears.
  • Containers. A container's memory limit may be lower than the host's. Size the Node limit to the container.

Better: build somewhere else

Building on the production server competes with your live site for memory and CPU, and a failed build can leave it half-updated. Build in CI, where memory is predictable and isolated, then deploy the finished files. If you must build on the server, stop non-essential services during the build or add swap as an emergency cushion, accepting that builds will be slow.

Need less memory

Raising the limit treats the symptom. To bring usage down:

  • Source maps. Generate them only when you need them, or upload them to your error-tracking service and keep them out of the main build step.
  • Type checking. Run the TypeScript check as a separate CI step rather than inside the bundler, so the two don't hold everything in memory together.
  • Parallelism. Many bundlers and site generators run several workers; each holds its own memory. Reducing the worker count can stop the crash on smaller machines.
  • Big dependencies. Look for huge libraries imported wholesale where a smaller import would do.
  • Build-time image processing. Large galleries optimised at build time use a lot of memory. Consider an image CDN or processing images once and caching them.
  • Huge static sites. Generating thousands of pages in one process may benefit from incremental builds or splitting.

Find out what's using memory

If memory keeps growing release after release, measure it. Node's documentation describes --heapsnapshot-near-heap-limit, which writes heap snapshots as the process approaches the limit. Open them in a browser's developer tools memory panel to see which objects dominate, for example source content held by a plugin.

Track peak memory of your build in CI over time, so you notice growth before it becomes a crash.

A worked example

An illustrative Montreal e-learning company built its course site on the same 2 GB server that ran it. As the course catalogue grew, builds started failing with "heap out of memory", sometimes taking the live site down with them. The developer moved builds to CI, set NODE_OPTIONS=--max-old-space-size=4096 on the runner, moved type checking to its own step and turned off production source maps in the main build. Builds became reliable, and the server only receives finished files.

FAQ

Is this a memory leak in my code?

Usually not; it's the build tool's normal usage outgrowing the limit. Leaks show up in long-running servers, not one-off builds.

Why does it work on my laptop?

Your laptop probably has much more memory than the CI runner or server.

Can I put the flag in package.json?

You can set NODE_OPTIONS in the build script, but CI settings are easier to adjust per environment.

Does upgrading Node help?

Sometimes, with newer garbage collection, but don't rely on it alone.

Should I use the percentage flag in CI?

It's convenient when runner sizes vary, but a fixed value is easier to reason about when diagnosing failures.

If your builds keep running out of memory, tell us where and how you build and we'll help you make them reliable.

Sources

WhatsAppBook a call