@bb-tools/withenv

This projects aims to simplify loading of environment variables with dotenv in a monorepo.

It consists of 2 parts:

• A withenv command which we use to call dotenv before running commands.
• A loadEnv function which you can reuse in any TS/JS code.

See the Configuration section for details about the .env.yaml file or continue reading for usage instructions.

Installation

npm install @bb-tools/withenv

Usage

withenv

Usage:

withenv <env> -- [command...]

Example:

withenv test -- jest

loadEnv

Usage:

import { loadEnv } from "withenv";

// Loads the environment into process.env
await loadEnv("test");

Configuration

Most of the magic behind withenv is a .env.yaml file whose goal is to define execution environments in a declarative way.

Example:

dev:
  nodeEnv: development
  files:
    - .env.dev

In this file, an environment named dev is declared.

As you might have guessed, when used with the dev environment, withenv will:

• Set the NODE_ENV environment variable value to development.

• Load non-sensitive environment variables from the .env.dev dotenv file located alongside the .env.yaml file.

• Load local overrides and secrets from the .env.dev.local dotenv file.

Environment options

The properties described in the table below can be used for each environment defined in the .env.yaml file.

Name	Description	Required	Default value
nodeEnv	The value of NODE_ENV to use	NO	Environment name if it exists in the NodeEnv enum of @kwentapay/node-utils package.
files	List of .env files to be loaded.	YES
alias	An optional alias to name the environment (e.g. development instead of dev)	NO

Local overrides

Local files can be defined for both the dotenv and withenv:

• <environment_file>.local (e.g. .env.local) to define local environment variables.

• .env.local.yaml to add new environments or override the existing ones.
  i.e.: This is where your personal secrets can be placed.

These files must be ignored by Git (documentation). For example, you can add the following lines to your .gitignore file:

*.local
*.local.yaml

More information

See:

• The src/load-env.ts file for details about the loading process.

• The src/config.ts file to see the configuration TS types.