Master Node.js Environment Variables: From Basics to .env Management

When building Node.js applications, developers typically develop locally and then deploy to internal servers, cloud servers, or containers (often Docker).

Since long ago, environment variables have been used to pass parameters, allowing applications to run differently without hard‑coding values, even for large text blocks.

This article introduces the basics of using environment variables and shows how to make an app run in various environments.

If your app hasn't adopted environment variables yet, this practical guide is a must‑read.

In Node.js, environment variables are essential; most apps use them for many tasks. The rule of thumb is: Any place that needs to change based on the environment should use an environment variable.

Common use cases include:

Startup parameters such as the listening PORT.

Sensitive paths or directories.

Identifying the current environment (development, production, etc.).

Secrets like passwords.

Debug flags, e.g., DEBUG=*.

Using Environment Variables

For example, an Express or Koa server often needs a port number that varies between development, testing, and production.

During development you may ignore it, but for deployment you retrieve it from process.env:

// server.js
const port = process.env.PORT;
console.log(`Your port is ${port}`);

You can start the app with the variable set from the shell:

PORT=8626 node server.js

Multiple variables can be passed in one command:

PORT=8626 NODE_ENV=development node server.js

Managing Variables with Files

When the number of variables grows, use a module like dotenv to load them from a .env file (never commit this file to version control).

# .env
NODE_ENV=development
PORT=8626
# Set your database/API connection information here
API_KEY=**************************
API_URL=**************************

Install the package:

npm i dotenv --save

Then load and use the variables:

// server.js
console.log(`Your port is ${process.env.PORT}`); // undefined
const dotenv = require('dotenv');
dotenv.config();
console.log(`Your port is ${process.env.PORT}`); // 8626

Initially the PORT is undefined; after calling dotenv.config() the values from .env are set and can be accessed the same way.

Advanced techniques include using node -r dotenv/config to preload the configuration without explicit code.

Our second TypeScript project is open‑source at https://github.com/midwayjs/midway, with ongoing IoC discussions in the issue tracker.