dotenv

Dotenv is a zero-dependency module that loads environment variables from a .env file into process.env. Storing configuration in the environment separate from code is based on The Twelve-Factor App methodology.

Watch the tutorial

Usage

Install it.

npm install dotenv --save

Create a .env file in the root of your project:

# .env
S3_BUCKET="YOURS3BUCKET"
SECRET_KEY="YOURSECRETKEYGOESHERE"

And as early as possible in your application, import and configure dotenv:

// index.js
require('dotenv').config() // or import 'dotenv/config' if you're using ES6
...
console.log(process.env) // remove this after you've confirmed it is working

$ node index.js
◇ injecting env (14) from .env

That's it. process.env now has the keys and values you defined in your .env file.

Advanced

Import with ES6:

import 'dotenv/config'

ES6 import if you need to set config options:

import dotenv from 'dotenv'
dotenv.config({ path: '/custom/path/to/.env' })

</details> <details><summary>bun</summary>

bun add dotenv

</details> <details><summary>yarn</summary>

yarn add dotenv

</details> <details><summary>pnpm</summary>

pnpm add dotenv

</details> <details><summary>Monorepos</summary>

For monorepos with a structure like apps/backend/app.js, put it the .env file in the root of the folder where your app.js process runs.

# app/backend/.env
S3_BUCKET="YOURS3BUCKET"
SECRET_KEY="YOURSECRETKEYGOESHERE"

</details> <details><summary>Multiline Values</summary>

If you need multiline variables, for example private keys, those are now supported (>= v15.0.0) with line breaks:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END RSA PRIVATE KEY-----"

Alternatively, you can double quote strings and use the \n character:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END RSA PRIVATE KEY-----\n"

</details> <details><summary>Comments</summary>

Comments may be added to your file on their own line or inline:

# This is a comment
SECRET_KEY=YOURSECRETKEYGOESHERE # comment
SECRET_HASH="something-with-a-#-hash"

Comments begin where a # exists, so if your value contains a # please wrap it in quotes. This is a breaking change from >= v15.0.0 and on.

</details> <details><summary>Parsing</summary>

The engine which parses the contents of your file containing environment variables is available to use. It accepts a String or Buffer and will return an Object with the parsed keys and values.

const dotenv = require('dotenv')
const buf = Buffer.from('BASIC=basic')
const config = dotenv.parse(buf) // will return an object
console.log(typeof config, config) // object { BASIC : 'basic' }

</details> <details><summary>Preload</summary>

Note: Consider using dotenvx instead of preloading. I am now doing (and recommending) so.

It serves the same purpose (you do not need to require and load dotenv), adds better debugging, and works with ANY language, framework, or platform. – motdotla

You can use the --require (-r) command line option to preload dotenv. By doing this, you do not need to require and load dotenv in your application code.

$ node -r dotenv/config your_script.js

The configuration options below are supported as command line arguments in the format dotenv_config_<option>=value

$ node -r dotenv/config your_script.js dotenv_config_path=/custom/path/to/.env dotenv_config_debug=true

Additionally, you can use environment variables to set configuration options. Command line arguments will precede these.

$ DOTENV_CONFIG_<OPTION>=value node -r dotenv/config your_script.js

$ DOTENV_CONFIG_ENCODING=latin1 DOTENV_CONFIG_DEBUG=true node -r dotenv/config your_script.js dotenv_config_path=/custom/path/to/.env

</details> <details><summary>Variable Expansion</summary>

Use dotenvx for variable expansion.

Reference and expand variables already on your machine for use in your .env file.

# .env
USERNAME="username"
DATABASE_URL="postgres://${USERNAME}@localhost/my_database"

// index.js
console.log('DATABASE_URL', process.env.DATABASE_URL)

$ dotenvx run --debug -- node index.js
⟐ injecting env (2) from .env · dotenvx@1.59.1
DATABASE_URL postgres://username@localhost/my_database

</details> <details><summary>Command Substitution</summary>

Use dotenvx for command substitution.

Add the output of a command to one of your variables in your .env file.

# .env
DATABASE_URL="postgres://$(whoami)@localhost/my_database"

// index.js
console.log('DATABASE_URL', process.env.DATABASE_URL)

$ dotenvx run --debug -- node index.js
⟐ injecting env (1) from .env · dotenvx@1.59.1
DATABASE_URL postgres://yourusername@localhost/my_database

</details> <details><summary>Encryption</summary>

Use dotenvx for encryption.

Add encryption to your .env files with a single command.

$ dotenvx set HELLO Production -f .env.production
$ echo "console.log('Hello ' + process.env.HELLO)" > index.js

$ DOTENV_PRIVATE_KEY_PRODUCTION="<.env.production private key>" dotenvx run -- node index.js
⟐ injecting env (2) from .env.production · dotenvx@1.59.1
Hello Production

learn more

</details> <details><summary>Multiple Environments</summary>

Use dotenvx to manage multiple environments.

Run any environment locally. Create a .env.ENVIRONMENT file and use -f to load it. It's straightforward, yet flexible.

$ echo "HELLO=production" > .env.production
$ echo "console.log('Hello ' + process.env.HELLO)" > index.js

$ dotenvx run -f=.env.production -- node index.js
Hello production
> ^^

or with multiple .env files

$ echo "HELLO=local" > .env.local
$ echo "HELLO=World" > .env
$ echo "console.log('Hello ' + process.env.HELLO)" > index.js

$ dotenvx run -f=.env.local -f=.env -- node index.js
Hello local

more environment examples

</details> <details><summary>Production</summary>

Use dotenvx for production deploys.

Create a .env.production file.

$ echo "HELLO=production" > .env.production

Encrypt it.

$ dotenvx encrypt -f .env.production

Set DOTENV_PRIVATE_KEY_PRODUCTION (found in .env.keys) on your server.

$ heroku config:set DOTENV_PRIVATE_KEY_PRODUCTION=value

Commit your .env.production file to code and deploy.

$ git add .env.production
$ git commit -m "encrypted .env.production"
$ git push heroku main

Dotenvx will decrypt and inject the secrets at runtime using dotenvx run -- node index.js.

</details> <details><summary>Syncing</summary>

Use dotenvx to sync your .env files.

Encrypt them with dotenvx encrypt -f .env and safely include them in source control. Your secrets are securely synced with your git.

This still subscribes to the twelve-factor app rules by generating a decryption key separate from code.

</details> <details><summary>More Examples</summary>

See examples of using dotenv with various frameworks, languages, and configurations.

Dotenv

Install / Use

README

dotenv

Usage

Advanced