How to Use Environment Variables in Node

This article is based on Node v16.14.0.

Environment variables provide information about the environment (production, development, build pipeline, etc.) in which the process is running. Node environment variables are used to handle sensitive data like passwords, API credentials, or anything else, which shouldn't be written directly in code. Any variables or configuration details, which might change between environments have to be configured through environment variables.

Environment Variables in Node.js

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

With Node.js environment variables are accessible on the global process.env object.

What are Environment Variables?

Environment variables allow your application to behave differently based on the environment in which the application is running in. Using environment variables to separate different configurations is best practice. Just consider one of these use cases:

• The production version of an application usually runs in a cloud environment (AWS, GCP, AZURE) or in a serverless function.
• One team member is using Linux, another one MacOS and another one Win10 to develop locally.
• The application runs in a docker container, for some users.
• For testing purposes you have to connect to the production version (load testing).

There can be quite some use cases and multiple scenarios, so rather than hard coding values that change based on environment, it is better and best practice, to make these environment variables.

In general, environment variables are variables whose value is set outside the process itself, and allow dynamic data between the different environments (host and specific). Environment variables are already part of the Node.js ecosystem and this is a big advantage against other configuration options like a config.js or, a config.json file. Especially, when you have an automation, like a build pipeline, environment variables allow you to avoid doing awkward things like scripting configuration files.

Common use cases for .env variables

The $HOME variable provided by the OS, which points to the home directory of the user. Any application has access to this variable and, can use it for different purposes. In Node.js applications .env variables are used for credentials, which should not be hard coded or change based on the environment. Other use cases are for example:

• Execution mode of application (production, stage, development)
• API keys
• Which HTTP port a server should use
• Configs that need to be secure
• location of the host environment's temporary files directory, etc.

Environment configuration vs. application configuration

It's important to distinguish between environment configuration and application configuration.

Environment configuration is any configuration that could vary per environment (staging, production, development) and should never exist in the code itself. Application configuration is a configuration, which doesn't vary between deploys/environments, like route configuration, which authentication middleware to use, content of emails, signup flows, or similar. This should be best kept in version control.

Reading environment variables with Node.js

Node.js loads automatically at runtime the environment variables into the global object process.env to make them available. To read an environment variable:

// hello.js
const name = process.env.NAME;
console.log(`Hello, ${name}!`);

Run hello.js and set the NAME environment variable for the process:

NAME="Mario" node hello.js

The output will be Hello, Mario!.

Setting environment variables for Node.js

In general, the host environment defines how environment variables are to set. This can vary in different cloud providers and different systems. The best way to handle this is to have a look in the documentation of the environment.

In a bash shell you can just simply export them:

export NAME='Mario'
export DEBUG=true

node ./hello.js

The output will be Hello, Mario!.

Using a .env file to set environment variables

Managing multiple environment variables for your application this way can be quite cumbersome. The most common solution in the Node.js world is to use the zero-dependency module dotenv, see dotenv github. This allows you to create a .env file in the root directory of your app, which contains key/value pairs defining the environment variables. The module dotenv reads this file and appends it to process.env, which makes it available for the application.

Never commit sensitive information to version control, use environment variables instead.

TL;DR

• Use dotenv to manage multiple environment variables in Node.
• Never commit sensitive information to version control.
• Handling of environment variables varies depending on the host system, refer to the specific docs for details.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

If you want to know more about Node, have a look at these Node Tutorials.

References (and Big thanks):

Node.js, Node.js docs HeyNode, dotenv