NODE_OPTIONS
A space-separated list of command-line options that are applied when starting any Node.js process. Allows setting flags like --max-old-space-size, --experimental-specifier-resolution, or --inspect globally without modifying scripts. Not all CLI options are supported.
Last updated:
NODE_OPTIONS lets you pass command-line flags to every Node.js process without editing the command that launches it — invaluable when the start command is buried inside a framework CLI, a Docker image, or an npm script you do not control. The most common real-world use is `--max-old-space-size` to lift the V8 heap limit (~2 GB on 64-bit by default) so large builds stop dying with 'JavaScript heap out of memory'. Only a curated subset of CLI flags is allowed; security-sensitive ones like `--experimental-policy` are rejected.
- Provider
- Node.js
- Category
- runtime
- Set by
- Set manually via environment variable
- Example
- --max-old-space-size=4096 --enable-source-maps
How to set NODE_OPTIONS
raise the heap limit (bash)
export NODE_OPTIONS=--max-old-space-size=4096
npm run buildenable source maps
NODE_OPTIONS='--enable-source-maps' node app.jsDocker
ENV NODE_OPTIONS="--max-old-space-size=2048"References
Frequently Asked Questions
How do I fix 'JavaScript heap out of memory' during a build?
Set NODE_OPTIONS=--max-old-space-size=4096 (value in MB) before running the build. This raises V8's old-space limit above its ~2 GB default. If it still crashes, the build likely has a genuine leak or an unbounded data structure rather than just needing more headroom.
Stay up to date
Get notified about new guides, tools, and cheatsheets.