dotenv-cra

Create React App style dotenv support for Node projects. Combine a base .env file with a .env.${NODE_ENV} file to create your optimum configuration.

Note: It's not recommended that you store secrets (like private API keys) in your .env file(s). Secret configuration values should be managed and provided as part of your hosting solution.

Install

npm i dotenv-cra

Usage

Not much new here. As with dotenv, import/require dotenv-cra and configure it as early as possible. This ensures that any modules reading values from process.env can retrieve the expected values.

⚠️ Warning: The NODE_ENV variable must be set, so you may choose to default it in your application before calling config().

import { config } from 'dotenv-cra';

process.env.NODE_ENV = process.env.NODE_ENV || 'development';
config();

Note When using NodeJS v15 or higher you can use Logical Nullish Assignment as well:

process.env.NODE_ENV ??= 'development';

At a minimum, create a base .env file in the root directory of your project with KEY=value entires on each line. However, if that's all you ever do, you don't need this library 😉. To see the real value of dotenv-cra, try creating a second .env.development file with some new and some overlapping KEY=value pairs.

# .env
LOG_LEVEL=info
PORT=3001

# .env.development
LOG_LEVEL=debug

# Loaded into process.env
LOG_LEVEL=debug
PORT=3001

What .env files can be used?

• .env: Default.
• .env.local: Local overrides. This file is loaded for all environments except test.
• .env.development, .env.test, .env.production: Environment-specific settings.
• .env.development.local, .env.test.local, .env.production.local: Local overrides of environment-specific settings.

Files on the left have more priority than files on the right:

• npm start: .env.development.local, .env.local, .env.development, .env
• npm test: .env.test.local, .env.test, .env (note .env.local is missing)

CRA Reference

Options

Env

Default: process.env.NODE_ENV

You may specify a custom environment if you don't want to base the .env.* files you load on NODE_ENV. For example, you may want NODE_ENV set to production, but you want to load the .env.staging file.

dotenvCra.config({ env: process.env.AWS_ENV });

Prefix

Default: none

You may specify a required prefix for your dotenv variables. For example, you may want to prefix your variables with WEB_API_ to ensure there aren't any collisions with other environment variables.

dotenvCra.config({ prefix: 'WEB_API_' });

Path

Default: path.resolve(process.cwd(), '.env')

You may specify a custom path if your file containing environment variables is located elsewhere. This will also be used as the basis for resolving the other .env.* files.

dotenvCra.config({ path: '/full/custom/path/to/your/.env' });

Encoding

Default: utf8

You may specify the encoding of your file containing environment variables. Passed through to dotenv.

dotenvCra.config({ encoding: 'latin1' });

Debug

Default: false

You may turn on logging to help debug why certain keys or values are not being set as you expect. Passed through to dotenv.

dotenvCra.config({ debug: process.env.DEBUG });

Credits

Thanks to these projects for this simple yet powerful approach 👏

• dotenv
• dotenv-expand
• create-react-app