@focus21/env

@focus21/env

Load environment variables from env files.

[[TOC]]

Usage

Installation:

pnpm add --save @focus21/env

Load env files from .env and .local.env and run my-command:

focus21-env .env my-command

Env File Syntax

Supports similar syntax to dotenv-expand, with a few additions and alterations.

Variables are defined linearly:

FOO="BAR"
BAZ="${FOO}"
FOO="QUX"

# Final values:
# BAZ="BAR"
# FOO="QUX"

Variables can also reference themselves, allowing setting default values for variables only if they aren't set:

FOO="${FOO:-default value}"
# FOO="default value"

Local Env Files

Local env files are automatically loaded by default:

# Loads both vars.env and vars.local.env
focus21-env vars.env my-command

Local env vars override regular env vars.

To disable loading the local env file, use --no-local:

focus21-env --no-local vars.env my-command

To duplicate all variables, set them to lowercase, and add TF_VAR_ for Terraform:

focus21-env --add-tf-var-prefix vars.env terraform ...

To add the special $DOCKER_HOST_USER environment variable:

focus21-env --add-docker-host-user vars.env my-command

The $DOCKER_HOST_USER environment variable can be used to share permissions between the current user and the Docker user.

Advanced Env File Syntax

Some features, such as quotation and escaping, are borrowed from sh/Bash. This allows shell files with only variables and quotes to be used.

This is markedly different than other Javascript env file tools as well as docker compose, so it's suggested just to use double quotes around every variable and to use backslashes when characters need to be escaped. This format is more widely supported.

The double quote/backslash format is used here for displaying final values.

# Spaces end variables unless if they are quoted or escaped.
# Mutliple variables can be set on the same line in this way:
SAMELINE_1="my var 1" SAMELINE_2="my var 2"
# Values:
# SAMELINE_1="my var 1"
# SAMELINE_2="my var 2"

# These are the same: FOO, "FOO", 'FOO'.
UNQUOTED=FOO
# Value: UNQUOTED="FOO"

# By using single quotes, dollar signs aren't interpretted as variable references.
# Using single quotes also escapes double quotes.
SINGLE_QUOTED='"${UNQUOTED}"'
# Value: SINGLE_QUOTED="\"${UNQUOTED}\""

# However, using double quotes, dollar signs are still interpretted normally.
# Using double quotes also escapes single quotes.
DOUBLE_QUOTED="'${UNQUOTED}'"
# Value: DOUBLE_QUOTED="'FOO'"

# Multiple quotes can be used in one variable:
MULTIPLE_QUOTES="FOO"'BAR'
# Value: MULTIPLE_QUOTES="FOOBAR"

# Dollar signs can also be escaped in this way.
# This works unquoted, with single quotes, and with double quotes.
ESCAPED=\${UNQUOTED}
# Value: ESCAPED="${UNQUOTED}"

# Multiline variables can be set with quotes or backslashes:
MULTILINE="FOO
BAR"
# Value: MULTILINE="FOO\nBAR"

# The "export" keyword is also ignored:
export EXPORTED=FOO
# Value: EXPORTED="FOO"