load

import { load } from "jsr:@ende/dotenv";

function · deprecated

async function load(options: LoadOptions = [UNSUPPORTED]): 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

GREETING=hello world

Then import the environment variables using the load function.

options: LoadOptions = [UNSUPPORTED]

The options

Deprecated.

This will be removed in 0.227.0. Use the --env-file flag or parse instead. See the module documentation for migration notes.

Returns

The parsed environment variables

Example: Basic usage

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

console.log(await load({ export: true })); // { GREETING: "hello world" }
console.log(Ende.env.get("GREETING")); // hello world

Run this with ende 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 "@ende/dotenv/load";

console.log(Ende.env.get("GREETING")); // hello world

Run this with ende 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 Ende.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 "@ende/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.

ende 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>" })

Source