{"id":15313,"library":"dotenv-flow","title":"dotenv-flow: Environment Variable Management","description":"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.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/kerimdzhanov/dotenv-flow","tags":["javascript","dotenv","node_env","development","test","production","local","env","environment","typescript"],"install":[{"cmd":"npm install dotenv-flow","lang":"bash","label":"npm"},{"cmd":"yarn add dotenv-flow","lang":"bash","label":"yarn"},{"cmd":"pnpm add dotenv-flow","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ES Modules and TypeScript, `dotenvFlow` is the default export containing the `config` method. `config` is not a named export.","wrong":"import { config } from 'dotenv-flow';","symbol":"dotenvFlow","correct":"import dotenvFlow from 'dotenv-flow';"},{"note":"This is the CommonJS way to programmatically load environment variables. Ensure this is called as early as possible in your application.","wrong":"import dotenvFlow from 'dotenv-flow'; dotenvFlow.config(); // This is ESM; using require() in ESM context is a syntax error","symbol":"config() (programmatic CJS)","correct":"require('dotenv-flow').config();"},{"note":"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';`","wrong":"import 'dotenv-flow/config';","symbol":"config (preload CJS)","correct":"require('dotenv-flow/config');"}],"quickstart":{"code":"// For this example, assume you have these files in your project root:\n// .env\n//   APP_NAME=MyUniversalApp\n//   GLOBAL_SETTING=true\n\n// .env.development\n//   NODE_ENV=development\n//   API_URL=http://localhost:3000\n\n// .env.development.local\n//   DB_USER=dev_local\n//   DEBUG_MODE=true\n\nimport dotenvFlow from 'dotenv-flow';\n\n// It's good practice to explicitly set NODE_ENV for predictable behavior,\n// though dotenv-flow also checks process.env.NODE_ENV.\n// For demonstration purposes, we can override it here.\n// In a real application, NODE_ENV would usually be set by the host environment.\n// For example: `NODE_ENV=development node app.js` or `NODE_ENV=production node app.js`\n\n// Simulate running in development for local testing\nprocess.env.NODE_ENV = process.env.NODE_ENV || 'development';\n\n// Load environment variables based on the current NODE_ENV\nconst result = dotenvFlow.config();\n\nif (result.error) {\n  console.error('Failed to load environment variables:', result.error);\n} else {\n  console.log(`Environment loaded for NODE_ENV: ${process.env.NODE_ENV}`);\n  console.log('--- Loaded Variables ---');\n  console.log('APP_NAME:', process.env.APP_NAME); // From .env\n  console.log('GLOBAL_SETTING:', process.env.GLOBAL_SETTING); // From .env\n  console.log('API_URL:', process.env.API_URL); // From .env.development\n  console.log('DB_USER:', process.env.DB_USER); // From .env.development.local\n  console.log('DEBUG_MODE:', process.env.DEBUG_MODE); // From .env.development.local\n  console.log('------------------------');\n\n  // Example of using a loaded variable\n  if (process.env.DEBUG_MODE === 'true') {\n    console.log('Debug mode is ENABLED. Happy coding!');\n  }\n}\n","lang":"typescript","description":"This quickstart demonstrates how to initialize dotenv-flow and access environment variables loaded from multiple `.env` files, simulating a `development` environment with local overrides."},"warnings":[{"fix":"Add `/.env.local` and `/.env.*.local` to your project's `.gitignore` file.","message":"Files 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"dotenv-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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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()`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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' })`.","cause":"dotenv-flow could not find the expected .env files at the specified path or in the current working directory.","error":"Error loading .env files: Error: ENOENT: no such file or directory, open '<path-to-file>'"},{"fix":"For ESM, use `import dotenvFlow from 'dotenv-flow';` for programmatic use or `import 'dotenv-flow/config';` for preloading.","cause":"Attempting to use CommonJS `require()` syntax within an ES Module (ESM) file.","error":"ReferenceError: require is not defined in ES module scope"},{"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.","cause":"Incorrect import syntax for ESM, trying to destructure `config` from the default export.","error":"TypeError: dotenvFlow.config is not a function"},{"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.","cause":"This often stems from an incorrect `NODE_ENV` setting, misunderstanding the file loading precedence, or the files themselves being malformed.","error":"My environment variables are not loading or have incorrect values."}],"ecosystem":"npm"}