npm dotenv: How to Set Up and Configure .env File in Node.js and Best Practices

Learn the best practices of using npm dotenv, know how it manages environment variables in Node.js. Load configuration from a .env file to keep sensitive keys safe, work with multiple environments, and simplify project setup without exposing credentials in your code.

Hard-coding API keys or database passwords into your code invites security issues. npm dotenv solves this by loading environment variables from .env file, keeping sensitive data separate from your application code. This guide explains how to set it up and manage environment-specific variables across different environments.

Understanding the Role of "dotenv"

One of the simplest ways to load environment variables into your application code is by using the zero-dependency dotenv module from npm.

When your app starts, you can preload dotenv using:

Copy
node -r dotenv/config your_script.js

This loads environment variables from a .env file into process.env before your script runs. The result: your app gets a clean set of environment-specific values without hard-coding sensitive data like API keys.

What’s the use of dotenv?

It lets you separate configuration from your code, following the Twelve-Factor App principle. A .env file stores environment variables in your project’s root directory. This makes it safer to store secrets—like API keys, database passwords, or production-specific configs—outside version control.

Setup Steps for Your Project

First, install the module:

Copy
npm install dotenv

Should you install as a dev dependency?

If you need dotenv in both development and production (e.g., loading DB credentials in both environments), install it as a normal dependency. Only use --save-dev if it’s strictly for local development.

In your application code (CommonJS syntax):

Copy
const dotenv = require('dotenv');
dotenv.config();

Or, in ES modules:

Copy
import dotenv from 'dotenv';
dotenv.config();

Here, calling dotenv.config() parses your .env file and injects the variables into process.env.

Tip: If you’re using ECMAScript Modules (ESM) in Node.js (i.e., import instead of require), then:

You must call dotenv.config() before importing any other module that uses environment variables. Otherwise, those modules will load before your environment is set and process.env will be empty in those files. —- LinkedIn Post

Using a Custom .env Path

You can tell dotenv to load a different env file without modifying your code:

This is ideal for managing environment-specific variables (e.g., , ).

Parsing and Expanding Variables

returns an object with:

• — the loaded key/value pairs
• — any error that occurred during parsing

You can reference one variable inside another by also using :

.env

index.js

Multiline variables are also supported, making it safe to store private keys without breaking parsing. If things don’t load as expected, you can enable debug output:

Want to manage your projects even faster? Try Rocket.new — instantly create, configure, and launch ready-to-code apps with dotenv pre-setup.

Start Building Your Project Now!

Workflows Across Environments

A typical workflow might load development database credentials locally, and production credentials on a server by pointing to a different file. For example:

This separation keeps secrets out of your code and version control.

Example: Config with Options

Accessing Environment Variables in Code

Once dotenv is configured, variables are available via :

This allows you to keep configuration outside of code—especially useful in cloud deployments, where env vars can be set without editing source files.

Common Usage Patterns

• Preload dotenv with in production and development.
• Load dotenv early in your app’s entry point.
• Use separate files: , , .
• Point to the right file by setting before running your app.

Example “Hello World” with dotenv

.env

index.js

Both quoted and unquoted values work fine.

Environment Variables Best Practices for npm dotenv Usage

Using dotenv to manage environment variables is straightforward, but applying best practices ensures security, maintainability, and scalability in different environments (development, staging, production). Below are the key recommendations:

1. Never Commit .env Files to Version Control

• .env files often contain sensitive information like API keys, database credentials, or private tokens.

• Always add to your file:

• Instead of committing the file, share it securely with your team through password managers or secure configuration services.

2. Use Separate .env Files for Different Environments

• Maintain separate files like:

• Specify the correct file in dotenv.config():

• This avoids overwriting production settings with development values.

3. Prefix Variable Names for Clarity

• Prefix variables with the project or service name to avoid conflicts.

  This becomes especially important when multiple projects run on the same machine or server.

4. Keep Variables Flat and Human-Readable

Avoid nesting structures in files — dotenv does not parse objects or arrays natively.

• Example:

5. Validate Required Environment Variables

Use a validation library (like envalid or joi ) to ensure all required environment variables are present and correctly formatted.

6. Document All Environment Variables

• Maintain a file containing all keys without sensitive values:

• This helps with onboarding new developers and avoids “it works on my machine” issues.

7. Load .env Early in Your Application

• Call at the very top of your entry file (before importing any module that depends on environment variables).

8. Avoid Hardcoding Defaults in Code

• If a default is needed, set it in .env or handle it gracefully:

9. Use Environment Variables for Configuration, Not Secrets in Production

• For high-security applications, consider storing secrets in AWS Secrets Manager, Vault, or similar services instead of plain files.
• .env is great for development, but has limitations in production security.

10. Reload Environment Variables When Needed

In long-running processes, environment variables are loaded only at startup. If you change .env mid-run, you’ll need to restart the app to apply updates.

Next Steps: Adopting npm dotenv with Confidence

Now you know how to:

• Configure dotenv
• Load variables from
• Work with multiple env files
• Use debug mode
• Apply variable expansion

Set up for development and production, enable debug mode if keys fail to load, and enjoy a safer, more maintainable configuration system.

# Preload dotenv before your script
node -r dotenv/config your_script.js

# Preload dotenv with a custom env file path
DOTENV_CONFIG_PATH=./custom.env node -r dotenv/config your_script.js

BASE_URL=http://localhost
API_URL=${BASE_URL}/api

import dotenv from 'dotenv';
import dotenvExpand from 'dotenv-expand';

const myEnv = dotenv.config();
dotenvExpand.expand(myEnv);

DEBUG=true node -r dotenv/config your_script.js

# Development
DOTENV_CONFIG_PATH=.env.development node -r dotenv/config app.js

# Production
DOTENV_CONFIG_PATH=.env.production node -r dotenv/config app.js

const path = require('path');
const dotenv = require('dotenv');

const result = dotenv.config({
  path: path.resolve(__dirname, '.env'), // default is .env in project root
  encoding: 'utf8',
  debug: process.env.DEBUG === 'true'
});

if (result.error) {
  console.error('Error loading .env:', result.error);
} else {
  console.log('Parsed keys:', Object.keys(result.parsed));
}

console.log(process.env.NODE_ENV);
console.log(process.env.API_KEY);

import dotenv from 'dotenv';
dotenv.config();

console.log(process.env.HELLO);    // hello world
console.log(process.env.GREETING); // hello world again

echo ".env" >> .gitignore

.env.development
.env.staging
.env.production

require('dotenv').config({ path: '.env.production' });

APP_DB_HOST=localhost
APP_DB_USER=root

const envalid = require('envalid');
const { str, num } = envalid;

envalid.cleanEnv(process.env, {
  API_URL: str(),
  API_TIMEOUT: num({ default: 5000 })
});

const port = process.env.PORT || 3000;