Cover image for Demystifying NODE_ENV var

Demystifying NODE_ENV var

koistya profile image Konstantin Tarkus ・2 min read

There might be some confusion regarding using NODE_ENV variable in Node.js apps. A few things you need to be aware of:

(1) Do not set NODE_ENV to anything other than production, development or test.

When you deploy your app to let's say Google Cloud Functions, the NODE_ENV variable will always be set to production, you will not be able to override it.

Similarly, when you run unit tests, the NODE_ENV variable will always be set to test by the test runner (this is a good default value that you don't want to mess around with, too many tools depend on it).

When you run your app locally, NODE_ENV needs to be set to development. If you're using a tool such as Webpack, it's going to be handled for you.

(2) Use custom environment variables such as APP_ENV, APP_VERSION to tell the app in which (deployment) environment it is running. For example:

  • http://localhost:8080 -> APP_ENV=local, APP_VERSION=latest
  • https://example.com -> APP_ENV=production, APP_VERSION=1
  • https://test.example.com -> APP_ENV=test, APP_VERSION=1

Most likely you want to use one of the following values for setting APP_ENV variable - production, staging, test (QA), development (shared development), or local (local development).

APP_VERSION can be set to latest or the OS username when you run/test the app locally. And once deployed it would be set to the actual version number by CI/CD pipeline. This will be particularly helpful when you need to notify users about the new version of the app that had been deployed:

(3) Ensure that the correct NODE_ENV (or, BABEL_ENV) variable is passed when you build the app with Babel for local testing vs production deployment.

P.S.: You will be surprised how many developers are struggling with this issue. Here is some random comment from GitHub:

Find a complete example of a Node.js application setup here:


Posted on by:

koistya profile

Konstantin Tarkus


Full-stack software engineer, virtual CTO


markdown guide