import * as mod from "https://deno.land/std@0.203.0/dotenv/mod.ts";
Load environment variables from a .env
file. Loaded variables are accessible
in a configuration object returned by the load()
function, as well as optionally
exporting them to the process environment using the export
option.
Inspired by the node modules dotenv
and dotenv-expand
.
Basic usage
# .env
GREETING=hello world
Then import the environment variables using the load
function.
// app.ts
import { load } from "https://deno.land/std@0.203.0/dotenv/mod.ts";
console.log(await load({export: true})); // { GREETING: "hello world" }
console.log(Deno.env.get("GREETING")); // hello world
Run this with deno run --allow-read --allow-env app.ts
.
.env files support blank lines, comments, multi-line values and more. See Parsing Rules below for more detail.
Auto loading
Import the load.ts
module to auto-import from the .env
file and into
the process environment.
// app.ts
import "https://deno.land/std@0.203.0/dotenv/load.ts";
console.log(Deno.env.get("GREETING")); // hello world
Run this with deno run --allow-read --allow-env app.ts
.
Files
Dotenv supports a number of different files, all of which are optional. File names and paths are configurable.
File | Purpose |
---|---|
.env | primary file for storing key-value environment entries |
.env.example | this file does not set any values, but specifies env variables which must be present in the configuration object or process environment after loading dotenv |
.env.defaults | specify default values for env variables to be used when there is no entry in the .env file |
Example file
The purpose of the example file is to provide a list of environment
variables which must be set or already present in the process environment
or an exception will be thrown. These
variables may be set externally or loaded via the .env
or
.env.defaults
files. A description may also be provided to help
understand the purpose of the env variable. The values in this file
are for documentation only and are not set in the environment. Example:
# .env.example
# With optional description (this is not set in the environment)
DATA_KEY=API key for the api.data.com service.
# Without description
DATA_URL=
When the above file is present, after dotenv is loaded, if either DATA_KEY or DATA_URL is not present in the environment an exception is thrown.
Defaults
This file is used to provide a list of default environment variables
which will be used if there is no overriding variable in the .env
file.
# .env.defaults
KEY_1=DEFAULT_VALUE
KEY_2=ANOTHER_DEFAULT_VALUE
# .env
KEY_1=ABCD
The environment variables set after dotenv loads are:
KEY_1=ABCD
KEY_2=ANOTHER_DEFAULT_VALUE
Configuration
Loading environment files comes with a number of options passed into
the load()
function, all of which are optional.
Option | Default | Description |
---|---|---|
envPath | ./.env | Path and filename of the .env file. Use null to prevent the .env file from being loaded. |
defaultsPath | ./.env.defaults | Path and filename of the .env.defaults file. Use null to prevent the .env.defaults file from being loaded. |
examplePath | ./.env.example | Path and filename of the .env.example file. Use null to prevent the .env.example file from being loaded. |
export | false | When true, this will export all environment variables in the .env and .env.default files to the process environment (e.g. for use by Deno.env.get() ) but only if they are not already set. If a variable is already in the process, the .env value is ignored. |
allowEmptyValues | false | Allows empty values for specified env variables (throws otherwise) |
Example configuration
import { load } from "https://deno.land/std@0.203.0/dotenv/mod.ts";
const conf = await load({
envPath: "./.env_prod",
examplePath: "./.env_required",
export: true,
allowEmptyValues: true,
});
Permissions
At a minimum, loading the .env
related files requires the --allow-read
permission. Additionally, if
you access the process environment, either through exporting your configuration or expanding variables
in your .env
file, you will need the --allow-env
permission. E.g.
deno run --allow-read=.env,.env.defaults,.env.example --allow-env=ENV1,ENV2 app.ts
Parsing Rules
The parsing engine currently supports the following rules:
- Variables that already exist in the environment are not overridden with
export: true
BASIC=basic
becomes{ BASIC: "basic" }
- empty lines are skipped
- lines beginning with
#
are treated as comments - empty values become empty strings (
EMPTY=
becomes{ EMPTY: "" }
) - single and double quoted values are escaped (
SINGLE_QUOTE='quoted'
becomes{ SINGLE_QUOTE: "quoted" }
) - new lines are expanded in double quoted values (
MULTILINE="new\nline"
becomes
{ MULTILINE: "new\nline" }
- inner quotes are maintained (think JSON) (
JSON={"foo": "bar"}
becomes{ JSON: "{\"foo\": \"bar\"}" }
) - whitespace is removed from both ends of unquoted values (see more on
trim
) (FOO= some value
becomes{ FOO: "some value" }
) - whitespace is preserved on both ends of quoted values (
FOO=" some value "
becomes{ FOO: " some value " }
) - dollar sign with an environment key in or without curly braces in unquoted
values will expand the environment key (
KEY=$KEY
orKEY=${KEY}
becomes{ KEY: "<KEY_VALUE_FROM_ENV>" }
) - escaped dollar sign with an environment key in unquoted values will escape the
environment key rather than expand (
KEY=\$KEY
becomes{ KEY: "\\$KEY" }
) - colon and a minus sign with a default value(which can also be another expand
value) in expanding construction in unquoted values will first attempt to
expand the environment key. If it’s not found, then it will return the default
value (
KEY=${KEY:-default}
If KEY exists it becomes{ KEY: "<KEY_VALUE_FROM_ENV>" }
If not, then it becomes{ KEY: "default" }
. Also there is possible to do this caseKEY=${NO_SUCH_KEY:-${EXISTING_KEY:-default}}
which becomes{ KEY: "<EXISTING_KEY_VALUE_FROM_ENV>" }
)
Interfaces
Load environment variables from a |