Manage JavaScript Environment Variables with dotenv

January 8, 2022 | 3 minutes

When working on a codebase, I often run into cases where I need to use API keys, URLs, or other values that I don't want to share with the Internet at large when I check in my code. There are many approaches to solving this problem, but I find myself often returning to using the package dotenv for my JavaScript projects. It's easy to use and works particularly well for small projects like my IoT programs.

Let's look at how it works and how you can use it in your next project.

What is dotenv and How Does It Work?

dotenv is a JavaScript package that's available through npm. When you include it in a project, it reads values from a .env file when you run your application, making them available on Node's process.env object. You can then access them in your application just like the traditional Node environment variables such as process.env.NODE_ENV.

Getting the environment variables from a separate file is helpful for two reasons:

  • It gives you a layer of separation between private values, such as API keys, and the code
  • You can add the .env file to the .gitignore file for your repo to prevent you from accidentally checking in the file

The downside is that if you're working on a collaborative project with others, each person needs a copy of the .env file with the private values. Since you won't check the .env file into your repo, you would need another way to distribute the file/values from the file with others. Typically, this happens over email, Slack, or another insecure communication tool. The dotenv team is currently working on Dotenv Sync to solve this problem, but it's not widely available yet. Depending on what's in your .env file and how many people will need access to the values, you may want to consider other options.

Sample Setup

There are different ways to use dotenv depending on whether you're using it in a project with CommonJS modules (Node12 and older) or ES modules (Node13+). To use dotenv in a project with CommonJS modules, do the following:

  1. Run npm install dotenv to [install it from npm] (
  2. Add require('dotenv').config() as early as possible in your code. You should include it before attempting to access a variable defined in the .env file.
  3. Create a .env file at the root of your codebase and add a key and value like below:
  1. Wherever you use the API key in your code, replace it with process.env.API_KEY, like below:
1// index.js
5const getData = async () => {
6    return await fetch(`${process.env.API_KEY}`);
  1. Run your application, and dotenv will replace process.env.API_KEY everywhere in your code with the API_KEY value from your .env file.

Suppose you're adding dotenv to a project with ES modules. In that case, the recommended approach is to run dotenv using the -r flag (which stands for --require) before running your application. This command will preload the environment variables. This approach works for CommonJS projects as well. As an example, you could update the start script in your application so that it automatically preloads the environment variables like this, "start": "node -r dotenv/config [your-script].js".

dev.env Files

In projects that use dotenv, it's common to include a dev.env file in the repo. This file aims to let new developers know that there are environment variables needed for the project. This file will typically include the keys for the environment variables with placeholder values.

Thumbnail photo by Myburgh Roux from Pexels