Node.js Production Flags: Which Runtime Flags Are Safe (and Which Will Break Your App)
Jenkins
Source: Dev.to | Dec 16, 2025 (UTC)
Node.js provides dozens of runtime flags, but very few are safe to use in production.
Misusing Node.js flags is a common cause of:
unstable performance
memory crashes
unpredictable behavior under load
This article explains Node.js production flags that are actually safe, which ones should be avoided, and how to think about runtime flags as part of your production contract.
If you run Node.js in production (Express, Fastify, containers, Kubernetes), this guide is for you.
What Are Node.js Runtime Flags?
Node.js runtime flags are command-line options passed to the node process that modify:
memory behavior
error handling
module loading
debugging and diagnostics
Example:
node --enable-source-maps dist/server.js
Enter fullscreen mode
Exit fullscreen mode
In production, runtime flags should be deliberate and minimal.
A Simple Rule for Node.js Production Flags
Before enabling any Node.js flag in production, ask:
Does this flag improve correctness, stability, or observability?
If the answer is “developer convenience” or “local debugging”, it does not belong in production.
Safe Node.js Flags for Production
These Node.js runtime flags are widely used in real production systems and have predictable behavior.
--enable-source-maps (Strongly Recommended)
node --enable-source-maps dist/server.js
Enter fullscreen mode
Exit fullscreen mode
What it does
Maps JavaScript stack traces back to the original source files.
Why it’s safe in production
Essential for TypeScript applications
Dramatically improves error diagnostics
Negligible performance overhead
If you run Node.js with TypeScript and don’t enable source maps, production debugging becomes guesswork.
--max-old-space-size (Memory Control)
node --max-old-space-size=1024 dist/server.js
Enter fullscreen mode
Exit fullscreen mode
What it does
Limits the V8 heap size in megabytes.
Why it’s important
Prevents unexpected out-of-memory kills
Makes Node.js memory usage predictable
Essential in Docker and Kubernetes
Best practice
Set this to 70–80% of container memory.
--unhandled-rejections=strict (Correctness)
node --unhandled-rejections=strict dist/server.js
Enter fullscreen mode
Exit fullscreen mode
What it does
Crashes the process on unhandled promise rejections.
Why it belongs in production
Exposes broken async code immediately
Prevents silent data corruption
Forces correct error handling
Unhandled promise rejections are one of the most common hidden Node.js production bugs.
--import / -r (Preloading for Instrumentation)
node --import ./dist/otel.js dist/server.js
Enter fullscreen mode
Exit fullscreen mode
or:
node -r ./dist/otel.js dist/server.js
Enter fullscreen mode
Exit fullscreen mode
What it does
Loads a module before your application starts.
Valid production use cases
OpenTelemetry instrumentation
Global diagnostics
Performance monitoring setup
Avoid
Business logic
Application configuration
Feature flags
Node.js preloading should prepare the runtime — not change application behavior.
--trace-warnings (Conditional Use)
node --trace-warnings dist/server.js
Enter fullscreen mode
Exit fullscreen mode
What it does
Adds stack traces to runtime warnings.
When to use
Staging environments
Short-term production debugging
Avoid leaving this enabled permanently due to log noise.
Node.js Flags You Should Avoid in Production
Many Node.js flags exist for development or debugging and should never run in production.
Development-Only Node.js Flags
Flag
Why It’s Unsafe
--watch
Auto-restart breaks stability
--inspect, --inspect-brk
Security risk
--loader ts-node/esm
Runtime TypeScript compilation
ts-node, tsx
Dev tooling only
Experimental Node.js Flags
Flag
Risk
--experimental-*
Unstable behavior
--experimental-fetch (older Node)
Inconsistent semantics
--experimental-vm-modules
Tooling only
If a flag is marked experimental, it is not production-ready.
High-Overhead Diagnostic Flags
Flag
Why to Avoid
--trace-gc
Severe performance impact
--prof
Profiling only
--trace-events-enabled
Heavy overhead
Use these flags only during controlled profiling sessions.
Node.js Runtime Flags vs Application Code
A healthy production system respects this boundary:
Node.js flags configure the runtime
Application code defines behavior
If a flag:
changes request handling
toggles features
alters business logic
…it’s being misused.
Recommended Node.js Production Startup Command
Most production Node.js applications need very few flags:
Залишити відповідь