npm package: @focus21/env
Description: Load environment variables from env files.
Author: Focus21
Latest version: 4.3.0

# @focus21/env

Load environment variables from env files.

[[_TOC_]]

## Usage

Installation:

```bash
pnpm add --save @focus21/env
```

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

```bash
focus21-env .env my-command
```

## Env File Syntax

<!-- Note: "bash" syntax is used in code blocks below for code highlighting even though it's not Bash code -->

Supports similar syntax to [dotenv-expand](https://github.com/motdotla/dotenv-expand),
with a few additions and alterations.

Variables are defined linearly:

```bash
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:

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

## Local Env Files

Local env files are automatically loaded by default:

```bash
# 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`:

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

To duplicate all variables, set them to lowercase, and add `TF_VAR_` for [Terraform](https://developer.hashicorp.com/terraform/language/values/variables#environment-variables):

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

To add the special `$DOCKER_HOST_USER` environment variable:

```bash
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](https://docs.docker.com/engine/reference/run/#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.

```bash
# 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"
```