DEV Community

Adarsh Hasnah
Adarsh Hasnah

Posted on

Node.js Production Flags: Which Runtime Flags Are Safe (and Which Will Break Your App)

#node #production #backend #devops

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:

node \
  --enable-source-maps \
  --max-old-space-size=1024 \
  --unhandled-rejections=strict \
  dist/server.js
Enter fullscreen mode Exit fullscreen mode

Add --import only when you use runtime instrumentation like OpenTelemetry.

Why Node.js Flags Are Part of Your Production Contract

Node.js runtime flags are not an implementation detail.

They directly affect:

  • memory behavior
  • error handling
  • observability

Changing flags is a production change, just like changing container limits or deployment configs.

Final Thoughts on Node.js Production Flags

Node.js gives you powerful runtime controls.

Production systems should use as few of them as possible.

If your application needs many Node.js flags to stay stable, the problem isn’t the flags — it’s the architecture.

Keep the Node.js runtime boring.

Boring systems are reliable systems.

Top comments (0)