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.
// shell: NODE_ENV=production node server.js
Try 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.
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
process.env.NODE_ENV // string | undefined
// 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 --testdoes not set it, andNODE_ENV=productiondoes 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 replaceprocess.env.NODE_ENVat build time and drop dead code. - Install behavior:
npm installskipsdevDependencieswhenNODE_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.
stagingshould usually beproductionwith 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,setin cmd, or--env-file. - Common mistake: leaving
NODE_ENVunset in production. Behavior then equals development in most libraries, with slower performance and more verbose errors.