A yummy dotenv library

An opinionated .env parsing library. Key features:

• read .env-files based on NODE_ENV, e.g. .env, .env.local, .env.development
• pass custom default values for your variables
• allow / prevent variable inclusion from proces.env
• use .env.schema to only allow certain values
• parameter expansion / interpolation of env-variables, e.g. GREET="Hello ${NAME}

Installation

1# npm
2npm i @yummy/dotenv
3
4# OR yarn
5yarn add @yummy/dotenv

Usage

This library makes some assumptions based on available .env-files. Unless configured otherwise, the following load order applies as follows:

• .env.defaults
• .env
• .env.local
• .env.${NODE_ENV}
• .env.${NODE_ENV}.local
• .env.schema
• process.env

The default options used are as follows:

1// for ES6, use `import dotenv from "@yummy/dotenv";`
2const dotenv = require("@yummy/dotenv");
3
4const env = dotenv.config({
5  // replaces process.env with what is parsed by this library. Set it to true
6  // if you want to opt into this.
7  override = false
8
9  // the directory to read the .env-files from
10  context = path.resolve(process.cwd()),
11
12  // allow system variables to take precedence
13  system = true,
14
15  // limit variables to keys specified in here
16  schema = '.env.schema',
17
18  // some default values for any environment, good for bootstrapping
19  defaults = '.env.defaults',
20
21  // the files to read (in that order)
22  files = [
23    '.env',
24    '.env.local',
25    `.env.${NODE_ENV}`,
26    `.env.${NODE_ENV}.local`,
27  ],
28});

.env.defaults

Use this to provide your dotenv config with some default values. Values defined in later files or process.env will override those. If your project does not have this file, then it will be ignored. You can also configure it to disable it explicitly or point it to another defaults file. Alternatively, you may pass an object to defaults.

1// the default value
2const env = dotenv.config({ defaults: ".env.defaults" });
3
4// point to a different file
5const env = dotenv.config({ defaults: "/<path>/<to>/.env.defaults" });
6
7// disable it explicitly
8const env = dotenv.config({ defaults: false });
9
10// pass as object, which will NOT attempt to read from file
11const env = dotenv.config({
12  defaults: { FOO: "default FOO value" },
13});

The behaviour is as follows:

1// $ cat .env.defaults
2// FOO='default foo'
3// BAR='default bar'
4//
5// $ cat .env
6// FOO='foo from .env'
7
8const env = dotenv.config();
9// => { FOO: 'foo from .env', BAR: 'default bar' }

.env.schema

You may wish to limit your dotenv variables to specific keys only. This is useful if you want to guard your application from an unexpected environment configuration.

1// the default value
2const env = dotenv.config({ schema: ".env.schema" });
3
4// point to a different file
5const env = dotenv.config({ schema: "/<path>/<to>/.env.schema" });
6
7// disable it explicitly
8const env = dotenv.config({ schema: false });

The behaviour is as follows:

1// $ cat .env.schema
2// FOO=
3//
4// $ cat .env
5// FOO='foo from .env'
6// BAR='bar from .env'
7
8const env = dotenv.config();
9// => { FOO: 'foo from .env'

process.env (system variables)

By default, system variables will be read. They take precedence over and are limited to variables defined in the .env-files. .env.defaults and .env.schema behavour still applies. You can disable this explicitly, of course.

1const env = dotenv.config({ system: true });
2
3// disable it
4const env = dotenv.config({ system: false });

The behaviour is as follows:

1// $ cat .env
2// FOO='foo from .env'
3// BAR='bar from .env'
4//
5// $ env
6// FOO='foo from system env'
7// BAZ='baz from system env' // will be ignored
8
9const env = dotenv.config();
10// => { FOO: 'foo from system  env', BAR: 'bar from .env' }

the .env file list

You can also configure the list of .env-files to read. The order of which also determines the read order when parsing those files. In case you pass files that do not exist, they will be ignored. .env.defaults and .env.schema behavour still applies.

1// $ cat .env
2// FOO='foo from .env'
3//
4// $ .env.custom
5// FOO='foo from custom env'
6
7const env = dotenv.config({ files: [".env", ".env.custom"] });
8// => { FOO: 'foo from custom env' }