Managing Environment Variables in Node.js

Environment variables let you change how your Node.js app runs without touching the code. You can use them to set things like API keys, database URLs, or app settings for different environments such as development, testing, or production.

This guide shows you how to use environment variables in Node.js, starting with the basics and moving on to more advanced techniques.

Prerequisites

Before getting started, make sure you have:

• Node.js installed on your system (version 20.x or newer recommended)
• Basic familiarity with running Node.js applications

Why use environment variables?

Environment variables offer several key benefits when building Node.js applications:

• They help you keep sensitive information like API keys and credentials from your code.
• You can easily change settings based on the environment: development, staging, or production.
• They make your app more portable, so you can run it in different environments without changing the code.
• They support best practices like the twelve-factor app approach used in modern software development.

Think of environment variables as an external configuration layer. They let you control how your app behaves without changing how it works on the inside.

Accessing environment variables

To use environment variables in Node.js, you don't need any extra libraries—Node.js gives you built-in access through the process.env object.

This object holds all the environment variables available to your app, and you can read from it just like a regular JavaScript object.

Create a new directory for our project:

mkdir env-demo && cd env-demo

Create a file named app.js:

console.log('Current user is:', process.env.USER);
console.log('Home directory is:', process.env.HOME);

Run the application:

node app.js

You should see output showing your system's environment variables:

Current user is: stanley
Home directory is: /Users/stanley

In this example, you're accessing environment variables that your operating system already provides: USER and HOME. These come built into your environment.

But you can also define your own environment variables. Let's look at how to do that next.

Setting variables for a single command

When you're just testing or want to temporarily set environment variables, the fastest method is to define them directly in the terminal as part of the command. This doesn't save the variables anywhere—they only exist for that one command execution. It's simple and effective for quick setups or one-off runs.

First, update your app.js file to read and display the environment variables:

console.log('Server port:', process.env.PORT);
console.log('API key:', process.env.API_KEY);

Now run your app with the variables set inline:

PORT=3000 API_KEY=abc123 node app.js

This should output:

Server port: 3000
API key: abc123

This approach works well when you only need the variables for a single run. But if you want the values to stick around during your terminal session, you can export them instead.

On Linux or macOS, run:

export PORT=3000

export API_KEY=abc123

Now you can run your app normally without redefining the variables each time:

node app.js

And you’ll still get:

Server port: 3000
API key: abc123

To make your app more reliable and flexible, it’s smart to add default values if the environment variables aren’t set. This prevents errors and keeps your app running with fallback settings.

Update app.js like this:

const port = process.env.PORT || 3000;
const apiKey = process.env.API_KEY || 'default-key';

console.log('Server port:', port);
console.log('API key:', apiKey);

Now your app will still work even if PORT or API_KEY aren’t set—using the defaults you’ve provided.

Using .env Files in Node.js 20+

Starting with Node.js 20, you can load environment variables from a .env file without extra libraries.

This built-in support makes it easier to manage configuration settings, especially when you want to keep sensitive or environment-specific values out of your code.

If you want to test .env files or run with fresh values, open a new terminal session or unset the exported variables first:

unset PORT

unset API_KEY

This clears the session-level variables, so your app can now load new values from a .env file or use the fallback values in your code.

Then, create a .env file in your project folder:

PORT=4000
API_KEY=secret-key-123
DATABASE_URL=mongodb://localhost:27017/myapp

This file contains key-value pairs that define your environment variables. Each variable is available to your application through process.env.

In your code, you can access the variables like this:

console.log('Server port:', process.env.PORT);
console.log('API key:', process.env.API_KEY);
console.log('Database URL:', process.env.DATABASE_URL);

To load the .env file, run your app with the --env-file flag:

node --env-file=.env app.js

When you run the app, you’ll see:

Server port: 4000
API key: secret-key-123
Database URL: mongodb://localhost:27017/myapp

Using multiple environment files

As your application moves through different stages of the development lifecycle, it requires different configurations.

Development environments need detailed logging and local resources, testing environments require isolated and reproducible conditions, while production environments prioritize performance, security, and reliability.

Using environment-specific .env files allows you to maintain these different configurations cleanly.

Start with a base .env file for shared settings:

NODE_ENV=development
LOG_LEVEL=info

Then create a file for development-specific variables:

PORT=4000
API_KEY=dev-key
DATABASE_URL=mongodb://localhost:27017/dev_db

And another for production:

PORT=8080
API_KEY=prod-key
DATABASE_URL=mongodb://prod-server:27017/prod_db

The .env file holds common values that apply across environments, while .development.env and .production.env define the settings for each environment.

Update your app to read and log these variables:

console.log('Environment:', process.env.NODE_ENV);
console.log('Log level:', process.env.LOG_LEVEL);
console.log('Server port:', process.env.PORT);
console.log('API key:', process.env.API_KEY);
console.log('Database URL:', process.env.DATABASE_URL);

Now run your app with both the shared and the environment-specific files.

For development:

node --env-file=.env --env-file=.development.env app.js

Environment: development
Log level: info
Server port: 4000
API key: dev-key
Database URL: mongodb://localhost:27017/dev_db

For production:

node --env-file=.env --env-file=.production.env app.js

Environment: development
Log level: info
Server port: 8080
API key: prod-key
Database URL: mongodb://prod-server:27017/prod_db

When you use multiple --env-file flags, Node.js loads the files in the order you specify.

If the same variable appears in more than one file, the value from the last file takes priority.

This gives you a clean way to separate shared settings from environment-specific ones while keeping everything easy to manage.

Using dotenv for older node.js versions

If you're working with an older version of Node.js (before version 20), built-in support for .env files isn't available. In that case, you can use the popular dotenv package to load environment variables from a .env file.

First, initialize your project and install dotenv:

npm init -y

npm install dotenv

Then enable ES modules (ESM) by setting the project type to module. You can do this by running:

npm pkg set type=module

Now create a .env file in your project directory:

PORT=4000
API_KEY=secret-key-123
DATABASE_URL=mongodb://localhost:27017/myapp

Update your app.js file to load the .env file using ESM syntax:

import dotenv from 'dotenv';

dotenv.config();

console.log('Server port:', process.env.PORT);
console.log('API key:', process.env.API_KEY);
console.log('Database URL:', process.env.DATABASE_URL);

Finally, run your application:

node app.js

The dotenv package reads the .env file and loads the variables into process.env, giving you similar behavior to Node.js 20’s built-in support—perfect for older versions.

Final thoughts

Environment variables make it easy to change how your Node.js app runs without touching the code. Whether you're running a quick test or managing different settings for development, testing, or production, they help keep your app clean, secure, and easy to manage.

Node.js 20 and newer can load .env files without any extra tools, while older versions can use the dotenv package to achieve the same result.

For more information, check out:

• Node.js Documentation

Got an article suggestion? Let us know

Next article

Getting Started with esbuild

Learn how to set up and use esbuild, a fast and lightweight JavaScript bundler, to streamline your development workflow. This step-by-step guide covers bundling, ESM support, watch mode, and styling with CSS—perfect for modern web development.

→

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.