Function load

load(options?): Promise<Record<string, string>>

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.

Note: The key needs to match the pattern /^[a-zA-Z_][a-zA-Z0-9_]*$/.

Basic usage

# .env
GREETING=hello world

Then import the environment variables using the load function.

Parameters

options: LoadOptions = {}
The options

Returns Promise<Record<string, string>>

The parsed environment variables

Example: Basic usage

// app.ts
import { load } from "@std/dotenv";

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.

Example: Auto-loading

// app.ts
import "@std/dotenv/load";

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

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.
export	false	When true, this will export all environment variables in the `.env` file 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.

Example configuration

Example: Using with options

import { load } from "@std/dotenv";

const conf = await load({
  envPath: "./.env_prod", // Uses .env_prod instead of .env
  export: true, // Exports all variables to the environment
});

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 --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 or KEY=${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 case KEY=${NO_SUCH_KEY:-${EXISTING_KEY:-default}} which becomes { KEY: "<EXISTING_KEY_VALUE_FROM_ENV>" })