Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js NODE_ENV environment variable

Reference for NODE_ENV in Node.js: it is a convention, not a built-in switch. See what libraries do with it, how to read it safely and common mistakes.

NODE_ENV is an environment variable that by convention names the environment a program runs in, usually development, test or production. Node.js itself never reads it and never sets it. Frameworks, libraries and your own code read process.env.NODE_ENV and change behavior accordingly: Express turns on view caching and terser error pages for production, React and many bundlers select a lean build, and logging libraries pick a log level.

Because it is only a string in process.env, it can be unset, misspelled or set to anything. Treat it as input that needs a default and validation.

NODE
// shell: NODE_ENV=production node server.js

Try it

Node.js Node.js does not set or interpret it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js A safe configuration pattern

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
process.env.NODE_ENV   // string | undefined
NODE
// shell
NODE_ENV=production node app.js           # macOS and Linux
$env:NODE_ENV = "production"; node app.js # PowerShell
node --env-file=.env app.js               # NODE_ENV=production inside .env
Value Typical meaning
development Readable errors, hot reload, verbose logging, no caching.
test Quiet output, in-memory or disposable resources.
production Optimized builds, caching on, minimal error detail shown to users.

Returns: a string, or undefined when it is not set. Assigning a value to process.env converts it to a string.

Edge cases: names such as prod, staging and Production are different values to every library that checks for the exact string 'production'; most simply fall back to development behavior.

Usage notes

  • It is a convention, not a feature of Node.js. node --test does not set it, and NODE_ENV=production does not make Node faster by itself. The speed-ups come from libraries that check it.
  • Frameworks key off the exact string production. Express enables view caching and hides stack traces in error responses; React and Vue select production builds; many bundlers replace process.env.NODE_ENV at build time and drop dead code.
  • Install behavior: npm install skips devDependencies when NODE_ENV=production (or with --omit=dev). Setting it during the build step but not at runtime, or the other way around, is a classic source of "works here, not there".
  • Do not add more modes than you need. staging should usually be production with different configuration values, not a separate code path.
  • Read it in one place, convert it to a typed setting object (as in the second example), and import that object everywhere else. Scattered string comparisons make typos invisible.
  • Never branch security behavior on it. Features like authentication must not depend on a variable that can be changed from outside; use explicit configuration with safe defaults.
  • Windows shells do not support NODE_ENV=production node app.js; use $env: in PowerShell, set in cmd, or --env-file.
  • Common mistake: leaving NODE_ENV unset in production. Behavior then equals development in most libraries, with slower performance and more verbose errors.