dotenv-flow

library0.4.0jsnpmunverified

dotenv-flow is an extension of the popular `dotenv` package, designed to simplify environment variable management across multiple deployment environments in Node.js applications. It introduces robust support for `NODE_ENV`-specific `.env` files (e.g., `.env.development`, `.env.production`, `.env.test`) and `.local` overrides (e.g., `.env.development.local`) to manage environment variables dynamically based on the current `NODE_ENV`. The package automatically loads the appropriate `.env` files in a predefined order, allowing variables in more specific files to override those in more general ones. This structured approach is inspired by Ruby's `dotenv-rails` and CreateReactApp's configuration patterns, adhering closely to the Twelve-Factor App methodology's principles for storing configuration in the environment. The current stable version is 4.1.0, with an active release cadence that regularly introduces new features and bug fixes, such as customizable file patterns in v4.0.0 and explicit file lists in v4.1.0, enhancing its flexibility and control over environment loading.

devops serialization

npm install dotenv-flow

github ↗package ↗

INSTALL

IMPORT

SIG · DOTENV-FLOW

dotenv-flow

devopsjavascriptv0.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

dotenvFlow

✓ import dotenvFlow from 'dotenv-flow';

✗ import { config } from 'dotenv-flow';

For ES Modules and TypeScript, `dotenvFlow` is the default export containing the `config` method. `config` is not a named export.

config() (programmatic CJS)

✓ require('dotenv-flow').config();

✗ import dotenvFlow from 'dotenv-flow'; dotenvFlow.config(); // This is ESM; using require() in ESM context is a syntax error

This is the CommonJS way to programmatically load environment variables. Ensure this is called as early as possible in your application.

config (preload CJS)

✓ require('dotenv-flow/config');

✗ import 'dotenv-flow/config';

This CommonJS specific import loads environment variables by preloading the configuration. It is typically used with `node -r` for convenience or in CJS modules that only need to load without explicit function calls. The ESM equivalent is `import 'dotenv-flow/config';`

This quickstart demonstrates how to initialize dotenv-flow and access environment variables loaded from multiple `.env` files, simulating a `development` environment with local overrides.

// For this example, assume you have these files in your project root: // .env // APP_NAME=MyUniversalApp // GLOBAL_SETTING=true // .env.development // NODE_ENV=development // API_URL=http://localhost:3000 // .env.development.local // DB_USER=dev_local // DEBUG_MODE=true import dotenvFlow from 'dotenv-flow'; // It's good practice to explicitly set NODE_ENV for predictable behavior, // though dotenv-flow also checks process.env.NODE_ENV. // For demonstration purposes, we can override it here. // In a real application, NODE_ENV would usually be set by the host environment. // For example: `NODE_ENV=development node app.js` or `NODE_ENV=production node app.js` // Simulate running in development for local testing process.env.NODE_ENV = process.env.NODE_ENV || 'development'; // Load environment variables based on the current NODE_ENV const result = dotenvFlow.config(); if (result.error) { console.error('Failed to load environment variables:', result.error); } else { console.log(`Environment loaded for NODE_ENV: ${process.env.NODE_ENV}`); console.log('--- Loaded Variables ---'); console.log('APP_NAME:', process.env.APP_NAME); // From .env console.log('GLOBAL_SETTING:', process.env.GLOBAL_SETTING); // From .env console.log('API_URL:', process.env.API_URL); // From .env.development console.log('DB_USER:', process.env.DB_USER); // From .env.development.local console.log('DEBUG_MODE:', process.env.DEBUG_MODE); // From .env.development.local console.log('------------------------'); // Example of using a loaded variable if (process.env.DEBUG_MODE === 'true') { console.log('Debug mode is ENABLED. Happy coding!'); } }

Debug

Known issues

gotchaFiles like `.env.local` and `.env.<NODE_ENV>.local` contain local-specific overrides and sensitive information. These should always be added to your `.gitignore` file to prevent accidental commitment to version control.

fix

Add `/.env.local` and `/.env.*.local` to your project's `.gitignore` file.

affects: >=1.0.0

gotchadotenv-flow loads environment variables based on a specific precedence: `.env` < `.env.<NODE_ENV>` < `.env.local` < `.env.<NODE_ENV>.local`. Variables defined in later files will override those defined in earlier ones. Misunderstanding this order can lead to unexpected variable values.

fix

Review the documentation on file precedence and carefully structure your `.env` files. Use `options.debug: true` (since v4.0.0) to see which files are being loaded.

affects: >=1.0.0

gotchaThe behavior of dotenv-flow is heavily reliant on the `NODE_ENV` environment variable. If `NODE_ENV` is not set, dotenv-flow defaults to `development` which might not be the intended behavior in production or test environments.

fix

Always explicitly set `NODE_ENV` in your deployment environment (e.g., `NODE_ENV=production node app.js`) or within your application startup script before calling `dotenvFlow.config()`.

affects: >=1.0.0

gotchaWhen using the programmatic `config()` method, ensure it is called as early as possible in your application's entry point to guarantee that environment variables are available throughout your codebase. Calling it too late may result in modules attempting to access `process.env` before it's populated.

fix

Place `require('dotenv-flow').config();` or `import dotenvFlow from 'dotenv-flow'; dotenvFlow.config();` at the very top of your main application file (e.g., `index.js` or `app.ts`).

affects: >=1.0.0

Errors

Common errors & fixes

Error loading .env files: Error: ENOENT: no such file or directory, open '<path-to-file>'

dotenv-flow could not find the expected .env files at the specified path or in the current working directory.

fix

Ensure your `.env` files are in the project root or provide the correct `path` option to `dotenvFlow.config({ path: '/absolute/path/to/project/root' })`.

ReferenceError: require is not defined in ES module scope

Attempting to use CommonJS `require()` syntax within an ES Module (ESM) file.

fix

For ESM, use `import dotenvFlow from 'dotenv-flow';` for programmatic use or `import 'dotenv-flow/config';` for preloading.

TypeError: dotenvFlow.config is not a function

Incorrect import syntax for ESM, trying to destructure `config` from the default export.

fix

Use `import dotenvFlow from 'dotenv-flow';` and then call `dotenvFlow.config();`. The `config` function is a method of the default `dotenvFlow` object, not a named export.

My environment variables are not loading or have incorrect values.

This often stems from an incorrect `NODE_ENV` setting, misunderstanding the file loading precedence, or the files themselves being malformed.

fix

Verify that `process.env.NODE_ENV` is correctly set for your desired environment. Check the order of your `.env` files for unintended overrides. Use `dotenvFlow.config({ debug: true })` (since v4.0.0) to output detailed loading information.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/kerimdzhanov/dotenv-flow ↗

packagehttps://www.npmjs.com/package/dotenv-flow ↗