Skip to content

BREAKING(dotenv): remove deprecated loaders #7335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tomas-zijdemans wants to merge 2 commits into
base: main
Choose a base branch
from
Open

BREAKING(dotenv): remove deprecated loaders #7335

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ee1735a
BREAKING(dotenv): remove deprecated loaders
tomas-zijdemans Sep 26, 2026
b6f83e4
test(dotenv): cover parse() process env expansion
tomas-zijdemans Sep 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion _tools/check_mod_exports.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@ for (const modFilePath of MOD_FILE_PATHS) {
maxDepth: 1,
skip: [
/unstable/,
/dotenv(\/|\\)load\.ts$/,
/front_matter(\/|\\)yaml\.ts$/,
/front_matter(\/|\\)json\.ts$/,
/front_matter(\/|\\)toml\.ts$/,
Expand Down
1 change: 0 additions & 1 deletion dotenv/deno.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
"version": "0.225.8",
"exports": {
".": "./mod.ts",
"./load": "./load.ts",
"./parse": "./parse.ts",
"./stringify": "./stringify.ts"
}
Expand Down
32 changes: 0 additions & 32 deletions dotenv/load.ts
View file
Open in desktop

This file was deleted.

54 changes: 0 additions & 54 deletions dotenv/load_test.ts
View file
Open in desktop

This file was deleted.

255 changes: 6 additions & 249 deletions dotenv/mod.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@
*
* ## Migrating from `load()`
*
* {@linkcode load}, {@linkcode loadSync} and the `@std/dotenv/load` side-effect
* module are deprecated in favor of the runtime's
* `load()`, `loadSync()` and the `@std/dotenv/load` side-effect module have been
* removed. Use the runtime's
* {@link https://docs.deno.com/runtime/reference/env_variables/ | --env-file}
* flag, which Node.js and Bun also support:
*
Expand All @@ -25,16 +25,16 @@
* deno run --env-file=.env --env-file=.env.local app.ts
* ```
*
* | Deprecated API | Replacement |
* | -------------- | ----------- |
* | Removed API | Replacement |
* | ----------- | ----------- |
* | `import "@std/dotenv/load"` | `deno run --env-file app.ts` |
* | `load({ export: true })` / `loadSync({ export: true })` | `--env-file` |
* | `load({ envPath: "./.env_prod" })` | `--env-file=.env_prod` |
* | `load()` (read into an object, no export) | `parse(await Deno.readTextFile(".env"))` |
*
* Differences to be aware of:
*
* - `load()` silently ignores a missing file. `--env-file` warns but continues,
* - `load()` silently ignored a missing file. `--env-file` warns but continues,
* while the `parse()` replacement above throws. To treat the file as
* optional:
*
Expand All @@ -49,7 +49,7 @@
* }
* ```
*
* - `$VAR` inside a double-quoted value stays literal with `load()` but
* - `$VAR` inside a double-quoted value stayed literal with `load()` but
* expands with `--env-file`. Use single quotes for values containing a
* literal `$`.
* - `${KEY:-default}` and nested defaults are not supported by `--env-file`.
Expand All @@ -61,248 +61,5 @@
* @module
*/

import { parse } from "./parse.ts";

export * from "./stringify.ts";
export * from "./parse.ts";

/**
* Options for {@linkcode load} and {@linkcode loadSync}.
*
* @deprecated This will be removed in 0.227.0. Use the
* {@link https://docs.deno.com/runtime/reference/env_variables/ | --env-file}
* flag or {@linkcode parse} instead. See the
* {@link https://jsr.io/@std/dotenv | module documentation} for migration
* notes.
*/
export interface LoadOptions {
/**
* Optional path to `.env` file. To prevent the default value from being
* used, set to `null`.
*
* @default {"./.env"}
*/
envPath?: string | URL | null;

/**
* Set to `true` to export all `.env` variables to the current processes
* environment. Variables are then accessible via `Deno.env.get(<key>)`.
*
* @default {false}
*/
export?: boolean;
}

/**
* Works identically to {@linkcode load}, but synchronously.
*
* @example Usage
* ```ts ignore
* import { loadSync } from "@std/dotenv";
*
* const conf = loadSync();
* ```
*
* @param options Options for loading the environment variables.
* @returns The parsed environment variables.
*
* @deprecated This will be removed in 0.227.0. Use the
* {@link https://docs.deno.com/runtime/reference/env_variables/ | --env-file}
* flag or {@linkcode parse} instead. See the
* {@link https://jsr.io/@std/dotenv | module documentation} for migration
* notes.
*/
export function loadSync(
options: LoadOptions = {},
): Record<string, string> {
const {
envPath = ".env",
export: _export = false,
} = options;
const conf = envPath ? parseFileSync(envPath) : {};

if (_export) {
for (const [key, value] of Object.entries(conf)) {
if (Deno.env.get(key) !== undefined) continue;
Deno.env.set(key, value);
}
}

return conf;
}

/**
* 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 {@linkcode https://github.com/motdotla/dotenv | dotenv}
* and {@linkcode https://github.com/motdotla/dotenv-expand | dotenv-expand}.
*
* Note: The key needs to match the pattern /^[a-zA-Z_][a-zA-Z0-9_]*$/.
*
* ## Basic usage
* ```sh
* # .env
* GREETING=hello world
* ```
*
* Then import the environment variables using the `load` function.
*
* @example Basic usage
* ```ts ignore
* // 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
* ```ts ignore
* // 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
* ```ts ignore
* 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.
*
* ```sh
* 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
* {@linkcode https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/Trim | 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>" }`)
*
* @param options The options
* @returns The parsed environment variables
*
* @deprecated This will be removed in 0.227.0. Use the
* {@link https://docs.deno.com/runtime/reference/env_variables/ | --env-file}
* flag or {@linkcode parse} instead. See the
* {@link https://jsr.io/@std/dotenv | module documentation} for migration
* notes.
*/
export async function load(
options: LoadOptions = {},
): Promise<Record<string, string>> {
const {
envPath = ".env",
export: _export = false,
} = options;
const conf = envPath ? await parseFile(envPath) : {};

if (_export) {
for (const [key, value] of Object.entries(conf)) {
if (Deno.env.get(key) !== undefined) continue;
Deno.env.set(key, value);
}
}

return conf;
}

function parseFileSync(
filepath: string | URL,
): Record<string, string> {
try {
return parse(Deno.readTextFileSync(filepath));
} catch (e) {
if (e instanceof Deno.errors.NotFound) return {};
throw e;
}
}

async function parseFile(
filepath: string | URL,
): Promise<Record<string, string>> {
try {
return parse(await Deno.readTextFile(filepath));
} catch (e) {
if (e instanceof Deno.errors.NotFound) return {};
throw e;
}
}
Loading
Loading