{"id":13464814,"url":"https://github.com/kerimdzhanov/dotenv-flow","last_synced_at":"2025-05-14T17:06:42.923Z","repository":{"id":38813764,"uuid":"133871478","full_name":"kerimdzhanov/dotenv-flow","owner":"kerimdzhanov","description":"Loads environment variables from .env.[development|test|production][.local] files for Node.js® projects.","archived":false,"fork":false,"pushed_at":"2024-09-12T05:42:05.000Z","size":520,"stargazers_count":879,"open_issues_count":4,"forks_count":35,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-10T04:53:27.335Z","etag":null,"topics":["configuration","dotenv","dotenv-flow","dx","env","environment","environment-variables","express-js","expressjs","node","node-env","node-js","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kerimdzhanov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-17T21:43:24.000Z","updated_at":"2025-03-31T06:26:24.000Z","dependencies_parsed_at":"2023-09-22T03:31:09.806Z","dependency_job_id":"b7924132-e941-49f7-aaef-e8fe11ffbf95","html_url":"https://github.com/kerimdzhanov/dotenv-flow","commit_stats":{"total_commits":134,"total_committers":11,"mean_commits":"12.181818181818182","dds":"0.11194029850746268","last_synced_commit":"7f07cf32cc28277f04e801982cc2fbddb6b220fa"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kerimdzhanov%2Fdotenv-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kerimdzhanov%2Fdotenv-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kerimdzhanov%2Fdotenv-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kerimdzhanov%2Fdotenv-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kerimdzhanov","download_url":"https://codeload.github.com/kerimdzhanov/dotenv-flow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254190396,"owners_count":22029632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration","dotenv","dotenv-flow","dx","env","environment","environment-variables","express-js","expressjs","node","node-env","node-js","nodejs"],"created_at":"2024-07-31T14:00:50.830Z","updated_at":"2025-05-14T17:06:42.903Z","avatar_url":"https://github.com/kerimdzhanov.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# dotenv-flow\n\n\u003cimg src=\"https://raw.githubusercontent.com/kerimdzhanov/dotenv-flow/master/dotenv-flow@2x.png\" alt=\"dotenv-flow\" width=\"280\" height=\"140\" align=\"right\" /\u003e\n\n\u003e _[dotenv](https://github.com/motdotla/dotenv) is a zero-dependency npm module that loads environment variables from a `.env` file into [`process.env`](https://nodejs.org/docs/latest/api/process.html#process_process_env)._\n\n**dotenv-flow** extends _dotenv_, adding support of `NODE_ENV`-specific `.env*` files _like `.env.development`, `.env.test`, `.env.stage`, and `.env.production`,_ and the appropriate `.env*.local` overrides.\n\nIt allows your app to have multiple environments _(like \"development\", \"test\", \"stage\", and \"production\" respectively)_ with selectively-adjusted environment variable setups and load them dynamically depending on the current `NODE_ENV`.\n\nIn addition to that, `.env*.local` overrides add the ability to overwrite variables locally for development, testing, and debugging purposes\n_(note that the appropriate `.env*.local` entry should be added to your `.gitignore`)_.\n\n🌱 Inspired by _Ruby's **dotenv** (a.k.a. `dotenv-rails`) gem_, _CreateReactApp's **storing configs in `.env*` files** approach_,\nthe _Twelve-Factor App methodology_ in general, and _its **[store config in the environment](https://12factor.net/config)** section_ in particular.\n\n[![Build Status](https://github.com/kerimdzhanov/dotenv-flow/actions/workflows/ci.yml/badge.svg?branch=master\u0026event=push)](https://github.com/kerimdzhanov/dotenv-flow/actions/workflows/ci.yml)\n[![npm version](https://badge.fury.io/js/dotenv-flow.svg)](https://badge.fury.io/js/dotenv-flow)\n[![Known Vulnerabilities](https://snyk.io/test/github/kerimdzhanov/dotenv-flow/badge.svg?targetFile=package.json)](https://snyk.io/test/github/kerimdzhanov/dotenv-flow?targetFile=package.json)\n[![npm downloads](https://badgen.net/npm/dw/dotenv-flow)](https://www.npmjs.com/package/dotenv-flow)\n\n## Installation\n\nUsing NPM:\n\n```sh\n$ npm install dotenv-flow --save\n```\n\nUsing Yarn:\n\n```sh\n$ yarn add dotenv-flow\n```\n\nUsing PNPM:\n\n```sh\n$ pnpm add dotenv-flow\n```\n\n\n## Usage\n\nAs early as possible in your Node.js app, initialize **dotenv-flow**:\n\n```js\nrequire('dotenv-flow').config();\n```\n\nIt will allow you to configure and use **dotenv-flow** from your code programmatically.\n\nIf you're using TypeScript or ES Modules:\n\n```ts\nimport dotenvFlow from 'dotenv-flow';\ndotenvFlow.config();\n```\n\nAlternatively, you can use the default config entry point that allows you to configure **dotenv-flow** using command switch flags or predefined environment variables:\n\n```js\nrequire('dotenv-flow/config');\n```\n\nOr even make **dotenv-flow** load environment variables for your app without adding it to the code using preload technique:\n\n```sh\n$ node -r \"dotenv-flow/config\" your_app.js\n```\n\nIt works with `ts-node` as well:\n\n```sh\n$ ts-node -r \"dotenv-flow/config\" your_app.ts\n```\n\n### How it works\nOnce **dotenv-flow** is initialized (using `.config` or any other method above), environment variables defined in your `.env*` files are loaded and become accessible in your Node.js app via `process.env.*`.\n\nFor example, let's suppose that you have the following `.env*` files in your project:\n\n```sh\n# .env\n\nDATABASE_HOST=127.0.0.1\nDATABASE_PORT=27017\nDATABASE_USER=default\nDATABASE_PASS=\nDATABASE_NAME=my_app\n```\n\n```sh\n# .env.local\n\nDATABASE_USER=local-user\nDATABASE_PASS=super-secret\n```\n\n```sh\n# .env.development\n\nDATABASE_NAME=my_app_dev\n```\n\n```sh\n# .env.test\n\nDATABASE_NAME=my_app_test\n```\n\n```sh\n# .env.production\n\nDATABASE_NAME=my_app_prod\n```\n\n```sh\n# .env.production.local\n\nDATABASE_HOST=10.0.0.32\nDATABASE_PORT=27017\nDATABASE_USER=devops\nDATABASE_PASS=1qa2ws3ed4rf5tg6yh\nDATABASE_NAME=application_storage\n```\n\n```js\n// your_script.js\n\nrequire('dotenv-flow').config();\n\nconsole.log('database host:', process.env.DATABASE_HOST);\nconsole.log('database port:', process.env.DATABASE_PORT);\nconsole.log('database user:', process.env.DATABASE_USER);\nconsole.log('database pass:', process.env.DATABASE_PASS);\nconsole.log('database name:', process.env.DATABASE_NAME);\n```\n\nAnd if you run `your_script.js` in the **development** environment, like:\n\n```sh\n$ NODE_ENV=development node your_script.js\n```\n\nyou'll get the following output:\n\n```text\ndatabase host: 127.0.0.1\ndatabase port: 27017\ndatabase user: local-user\ndatabase pass: super-secret\ndatabase name: my_app_dev\n```\n\nOr if you run the same script in the **production** environment:\n\n```sh\n$ NODE_ENV=production node your_script.js\n```\n\nyou'll get the following:\n\n```text\ndatabase host: 10.0.0.32\ndatabase port: 27017\ndatabase user: devops\ndatabase pass: 1qa2ws3ed4rf5tg6yh\ndatabase name: application_storage\n```\n\nNote that the `.env*.local` files should be ignored by your version control system (refer the [Files under version control](#files-under-version-control) section below to learn more), and you should have the `.env.production.local` file only on your production deployment machine.\n\n\n### `NODE_ENV`-specific env files\n\nActually, **dotenv-flow** doesn't have any predefined environment names, so you may use whatever names you want.\nHowever, it's a good practice to use the world's universally recognized environment names like `development`, `test`, `production`, as well as frequently used `qa` or `stage`.\n\nThe naming convention for `NODE_ENV`-specific files is simply as `.env.${NODE_ENV}[.local]` (i.e. `.env.development`, `.env.test`, `.env.production`, `.env.development.local`, `.env.production.local`, etc.).\n\nTo activate specific environment run your application with predefined `NODE_ENV` environment variable, like:\n\n```sh\n$ export NODE_ENV=production\n$ node your_script.js\n```\n\nor:\n\n```sh\n$ NODE_ENV=production node your_script.js\n```\n\nIf you are on Windows:\n\n```bat\n\u003e SET NODE_ENV=production\n\u003e node your_script.js\n```\n\nOr even better, use [cross-env](https://github.com/kentcdodds/cross-env) to make it work independent of platform:\n\n```sh\n$ cross-env NODE_ENV=production node your_script.js\n```\n\nThe `--node-env` switch is also supported:\n\n```sh\n$ node your_script.js --node-env=production\n```\n\n\n### Preload\n\nAlternatively, you can preload **dotenv-flow** using node's [`-r` (`--require`) command line option](https://nodejs.org/api/cli.html#cli_r_require_module).\n\n```sh\n$ NODE_ENV=production node -r dotenv-flow/config your_script.js\n```\n\nor:\n\n```sh\n$ node -r dotenv-flow/config your_script.js --node-env=production\n```\n\nYou can also use environment variables to set configuration options when preloading the `dotenv-flow/config`:\n\n```sh\n$ DOTENV_FLOW_PATH=/path/to/env-files-dir node -r dotenv-flow/config your_script.js\n```\n\nRefer to the [`dotenv-flow/config` options](#dotenv-flowconfig-options) section below to see all available options.\n\n\n## Files under version control\n\nThe main point here is not to commit production database passwords, API keys and other sensitive things to your source code repository,\nbut it's still nice to have default database connections, ports, hosts, etc., for development and testing purposes to keep your code clean and simple.\n\nUnderstanding the above, we have the following approach:\n\nYou can keep all the fallback values in the default `.env` file, that (if exists) will always be loaded by default.\nAlso, it is a good place to have all the application used environment variables there, thus having a reference of environment variables that are used by your application on the whole.\nSo it is a good reason to share the `.env` file with other developers in your team, but keep all the sensitive data on your own (or production) machine locally in the `.env*.local` files.\n\nIt is not necessary, but also a good practice to use `NODE_ENV` to control the environment to run your application in.\nAnd if you follow this practice you can keep the `NODE_ENV`-specific defaults in your `.env.development`, `.env.test`, `.env.production` files sharing them with your team as well.\nAny `NODE_ENV`-specific `.env.*` file's values can also be overwritten in the appropriate `.env.*.local` file (i.e. `.env.development.local`, `.env.test.local`, `.env.production.local`).\n\nSummarizing the above, you can have the following `.env*` files in your project:\n\n * `.env` – for default (fallback) values, **tracked** by VCS\n * `.env.development` – for development environment, **tracked** by VCS\n * `.env.test` – for test environment, **tracked** by VCS\n * `.env.production` – for production environment, **tracked** by VCS\n * `.env.local` – for individual default values, **ignored** by VCS\n * `.env.development.local` – for individual development environment values, **ignored** by VCS\n * `.env.test.local` – for individual test environment values, **ignored** by VCS\n * `.env.production.local` – for production environment values (DB passwords, API keys, etc.), **ignored** by VCS\n\nNote that `.env.*` file names may vary in your project depending on your own needs/preferences, just keep in mind that `.env*.local` files should be untracked (ignored) by your version control system.\n\nHere is an example of the `.gitignore` (or `.hgignore`) file entry to keep it clear:\n\n```gitignore\n# local .env* files\n.env.local\n.env.*.local\n```\n\n\n## Variables overwriting/priority\n\nSince multiple `.env*` files are loaded simultaneously, all the variables defined in these files are merged in the following order:\n\n1) The `.env` file has the lowest priority. _Keep the most default (fallback) values there_;\n2) The `.env.local` file has a priority over the `.env` (except when `NODE_ENV=test`, in which case this file is not loaded). _Create it if you want to overwrite the default values for your own environment-specific needs_;\n3) `NODE_ENV`-specific env files (like `.env.development`, `.env.test`, etc.) have a priority over the default `.env` and `.env.local` files. _Keep `NODE_ENV`-specific environment variables there_;\n4) `NODE_ENV`-specific local env files (`.env.development.local`, `.env.production.local`, etc.) have the highest priority over all the env files. _As with `.env.local`, create them only if you need to overwrite `NODE_ENV`-specific values for your own environment-specific needs_;\n5) Environment variables that are already set will not be overwritten, that means that the command line variables have a higher priority over all those defined in env files;\n\n\n## Alternative defaults: `.env.defaults` \n\nIn addition to `.env`, you may also use `.env.defaults` to store default (fallback) values.\n\nThis may come handy e.g. when migrating from [dotenv](https://github.com/motdotla/dotenv) (where it is strongly advised against committing `.env` file to VCS)\nand you already have `.env` file used to store your local values.\n\nIn such case, you may prefer to keep using your existing `.env` (**ignored** by VCS) as your local config\nand create additional `.env.defaults` (**tracked** by VCS) file which will be loaded before `.env`. \n\nThen at every place `.env` is mentioned in the docs, read it as: \"`.env.defaults` first, then `.env`\".\n\n\n## `dotenv-flow/config` options\n\nThe following configuration options can be used when:\n- a) preloading **dotenv-flow** using Node's `-r` (`[ts-]node --require`) switch, or…\n- b) `require`ing the `dotenv-flow/config` entry point (using `require('dotenv-flow/config');`).\n\n### Environment variables\n\n* `NODE_ENV` =\u003e [`options.node_env`](#optionsnode_env);\n* `DEFAULT_NODE_ENV` =\u003e [`options.default_node_env`](#optionsdefault_node_env);\n* `DOTENV_FLOW_PATH` =\u003e [`options.path`](#optionspath);\n* `DOTENV_FLOW_PATTERN` =\u003e [`options.pattern`](#optionspattern);\n* `DOTENV_FLOW_ENCODING` =\u003e [`options.encoding`](#optionsencoding);\n* `DOTENV_FLOW_PURGE_DOTENV` =\u003e [`options.purge_dotenv`](#optionspurge_dotenv);\n* `DOTENV_FLOW_DEBUG` =\u003e [`options.debug`](#optionsdebug);\n* `DOTENV_FLOW_SILENT` =\u003e [`options.silent`](#optionssilent);\n\n##### _for example:_\n```sh\n$ NODE_ENV=production DOTENV_FLOW_PATH=/path/to/env-files-dir node -r dotenv-flow/config your_script.js\n```\n\n### Command line switches\n\n* `--node-env` =\u003e [`options.node_env`](#optionsnode_env);\n* `--default-node-env` =\u003e [`options.default_node_env`](#optionsdefault_node_env);\n* `--dotenv-flow-path` =\u003e [`options.path`](#optionspath);\n* `--dotenv-flow-pattern` =\u003e [`options.pattern`](#optionspattern);\n* `--dotenv-flow-encoding` =\u003e [`options.encoding`](#optionsencoding);\n* `--dotenv-flow-purge-dotenv` =\u003e [`options.purge_dotenv`](#optionspurge_dotenv);\n* `--dotenv-flow-debug` =\u003e [`options.debug`](#optionsdebug);\n* `--dotenv-flow-silent` =\u003e [`options.silent`](#optionssilent);\n\n\u003e Make sure that **dotenv-flow/config**-specific CLI switches are separated from Node's by `--` (double dash) since they are not recognized by **Node.js**.\n\n##### _for example:_\n```sh\n$ node --require dotenv-flow/config your_script.js -- --dotenv-flow-path=/path/to/project --dotenv-flow-encoding=base64\n```\n\n\n## API reference\n\n#### `.config([options]) =\u003e object`\n\n\"dotenv-flow\" initialization function (API entry point).\n\nAllows configuring dotenv-flow programmatically.\n\nAlso, like the original module ([dotenv](https://github.com/motdotla/dotenv)),\nit returns an `object` with `.parsed` property containing the resulting\n`varname =\u003e values` pairs or `.error` property if the initialization is failed.\n\n##### `options.node_env`\n###### Type: `string`\n###### Default: `process.env.NODE_ENV`\n\nWith the `node_env` option you can force the module to use your custom environment value independent of `process.env.NODE_ENV`:\n\n```js\nrequire('dotenv-flow').config({\n  node_env: process.argv[2] || 'development'\n});\n```\n\n##### `options.default_node_env`\n###### Type: `string`\n###### Default: _undefined_\n\nIf the `NODE_ENV` environment variable is not set, the module doesn't load/parse any `NODE_ENV`-specific files at all.\nTherefore, you may want to use `\"development\"` as a default environment, like:\n\n```js\nrequire('dotenv-flow').config({\n  default_node_env: 'development'\n});\n```\n\nTo be clear, just make a note that all the following initialization examples are also equivalent:\n\n```js\nprocess.env.NODE_ENV = process.env.NODE_ENV || 'development';\n\nrequire('dotenv-flow').config();\n```\n\n```js\nrequire('dotenv-flow').config({\n  node_env: process.env.NODE_ENV || 'development'\n});\n```\n\n```js\nrequire('dotenv-flow').config({\n  node_env: process.env.NODE_ENV,\n  default_node_env: 'development'\n});\n```\n\nAll the examples above, considers the value of `process.env.NODE_ENV` at first, and if it is not set, uses `\"development\"` as the value by default.\nYou can just choose one that looks prettier for you.\n\n##### `options.path`\n###### Type: `string`\n###### Default: `process.cwd()` _(current working directory)_\n\nWith the `path` initialization option you can specify a path to `.env*` files directory:\n\n```js\nrequire('dotenv-flow').config({\n  path: '/path/to/env-files-dir'\n});\n```\n\nIf the option is not provided, the current working directory is used.\n\n##### `options.pattern`\n###### Type: `string`\n###### Default: `\".env[.node_env][.local]\"`\n\nAllows you to change the default `.env*` files' naming convention\nif you want to have a specific file naming structure for maintaining\nyour environment variables' files.\n\n**Default Value**\n\nThe default value `\".env[.node_env][.local]\"` makes *dotenv-flow* look up\nand load the following files in order:\n\n1. `.env`\n2. `.env.local`\n3. `.env.${NODE_ENV}`\n4. `.env.${NODE_ENV}.local`\n\nFor example, when the `proess.env.NODE_ENV` (or `options.node_env`) is set to `\"development\"`,\n*dotenv-flow* will be looking for and parsing (if found) the following files:\n\n1. `.env`\n2. `.env.local`\n3. `.env.development`\n4. `.env.development.local`\n\n**Custom Pattern**\n\nHere is a couple of examples of customizing the `.env*` files naming convention:\n\nFor example, if you set the pattern to `\".env/[local/]env[.node_env]\"`,\n*dotenv-flow* will look for these files instead:\n\n1. `.env/env`\n2. `.env/local/env`\n3. `.env/env.development`\n4. `.env/local/env.development`\n\n… or if you set the pattern to `\".env/[.node_env/].env[.node_env][.local]\"`,\n*dotenv-flow* will try to find and parse:\n\n1. `.env/.env`\n2. `.env/.env.local`\n3. `.env/development/.env.development`\n4. `.env/development/.env.development.local`\n\n› Please refer to [`.listFiles([options])`](#listfiles-options--string) to dive deeper.\n\n##### `options.files`\n###### Type: `string[]`\n\nAllows explicitly specifying a list (and the order) of `.env*` files to load.\n\nNote that options like `node_env`, `default_node_env`, and `pattern` are ignored in this case.\n\n```js\nrequire('dotenv-flow').config({\n  files: [\n    '.env',\n    '.env.local',\n    `.env.${process.env.NODE_ENV}`, // '.env.development'\n    `.env.${process.env.NODE_ENV}.local` // '.env.development.local'\n  ]\n});\n```\n\n##### `options.encoding`\n###### Type: `string`\n###### Default: `\"utf8\"`\n\nYou can specify the encoding for reading your files containing environment variables.\n\n```js\nrequire('dotenv-flow').config({\n  encoding: 'base64'\n});\n```\n\n##### `options.purge_dotenv`\n###### Type: `boolean`\n###### Default: `false`\n\nIn some cases the original \"dotenv\" library can be used by one of the dependent\nnpm modules. It causes calling the original `dotenv.config()` that loads\nthe `.env` file from your project before you can call `dotenv-flow.config()`.\n\nSuch cases breaks `.env*` files priority because the previously loaded\nenvironment variables are treated as shell-defined thus having a higher priority.\n\nSetting the `purge_dotenv` option to `true` can gracefully fix this issue.\n\n```js\nrequire('dotenv-flow').config({\n  purge_dotenv: true\n});\n```\n\n##### `options.debug`\n###### Type: `boolean`\n###### Default: `false`\n\nEnables detailed logging to debug why certain variables are not being set as you expect.\n\n##### `options.silent`\n###### Type: `boolean`\n###### Default: `false`\n\nSuppresses all kinds of warnings including \".env*\" files' loading errors.\n\n```js\nrequire('dotenv-flow').config({\n  silent: true\n});\n```\n\n---\n\nThe following API is considered as internal, although it's exposed\nfor programmatic use of **dotenv-flow** for your own project-specific needs.\n\n\n#### `.listFiles([options]) =\u003e string[]`\n\nReturns a list of existing `.env*` filenames depending on the given `options`.\n\nThe resulting list is ordered by the env files'\nvariables overwriting priority from lowest to highest.\n\nThis can also be referenced as \"env files' environment cascade\"\nor \"order of ascending priority.\"\n\n⚠️ Note that the `.env.local` file is not listed for \"test\" environment,\nsince normally you expect tests to produce the same results for everyone.\n\n##### Parameters:\n\n##### `options.node_env`\n###### Type: `string`\n###### Default: _undefined_\n\nThe node environment (a.k.a. `process.env.NODE_ENV`).\n\nThe conventionally used values are `\"development\"`, `\"test\"`\n(or `\"staging\"`) and `\"production\"`, also commonly used are `\"qa\"`, `\"uat\"`, `\"ci\"`.\n\n\n##### `options.pattern`\n###### Type: `string`\n###### Default: `\".env[.node_env][.local]\"`\n\n`.env*` files' naming convention pattern.\n\nThe default one, (`\".env[.node_env][.local]\"`) without `options.node_env` given,\nproduces the following list of filenames:\n\n- `.env`\n- `.env.local`\n\nWhen `options.node_env` is set, for example to `\"development\"`,\nit appends \"node_env-specific\" filenames, that will make `.listFiles` to return:\n\n- `.env`\n- `.env.local`\n- `.env.development`\n- `.env.development.local`\n\nAnother example might be the pattern `\".env/[local/]env[.node_env]\"`,\nthat without `options.node_env` will produce:\n\n- `.env/env`\n- `.env/local/env`\n\n… and if `options.node_env` is set to (for example) `\"development\"`,\nwill append \"node_env-specific\" files producing the following:\n\n- `.env/env`\n- `.env/local/env`\n- `.env/env.development`\n- `.env/local/development`\n\nAlso, note that if `[node_env]` placeholders is missing in the pattern,\nnone of the \"node_env-specific\" files fill be listed.\nFor example, a pattern like `\".env[.local]\"`,\nindependently of whether the `options.node_env` is set, will always produce:\n\n- `.env`\n- `.env.local`\n\n… except the case when `options.node_env` is set to `\"test\"`,\nwhich (as mentioned above) will exclude `.env.local` producing just a single:\n\n- `.env`\n\n… since normally we expect tests to produce the same results for everyone.\n\n\n##### `options.debug`\n###### Type: `boolean`\n###### Default: `false`\n\nEnables debug messages.\n\n\n##### Returns:\n\n###### Type: `string[]`\n\nA list of `.env*` filenames.\n\n\n##### Example:\n\n```js\nconst dotenvFlow = require('dotenv-flow');\n\nconst filenames = dotenvFlow.listFiles({ node_env: 'development' });\n\nconsole.log(filenames); // will output the following:\n// \u003e [ '/path/to/project/.env.defaults',\n// \u003e   '/path/to/project/.env',\n// \u003e   '/path/to/project/.env.local',\n// \u003e   '/path/to/project/.env.development',\n// \u003e   '/path/to/project/.env.development.local' ]\n```\n\n\n#### `.parse(filenames, [options]) =\u003e object`\n\nParses the content of a given file(s) to use the result programmatically. Accepts a filename or a list of filenames and returns a map of the parsed key/values as an object.\n\nWhen several filenames are given, the parsed variables are merged into a single object using the \"overwrite\" strategy.\n\n\n##### Parameters:\n\n##### `filenames`\n###### Type: `string|string[]`\n\nA filename or a list of filenames to parse.\n\n\n##### `options.encoding`\n###### Type: `string`\n###### Default: `\"utf8\"`\n\nAn optional encoding for reading files.\n\n\n##### `options.debug`\n###### Type: `boolean`\n###### Default: `false`\n\nEnables debug messages.\n\n\n##### Returns:\n\n###### Type: `object`\n\nThe resulting map of `{ env_var: value }` as an object.\n\n\n##### Example:\n\n```sh\n# .env\n\nFOO=bar\nBAZ=bar\n```\n\n```sh\n# .env.local\n\nBAZ=qux\n```\n\n```js\nconst dotenvFlow = require('dotenv-flow');\n\nconst variables = dotenvFlow.parse([\n  '/path/to/project/.env',\n  '/path/to/project/.env.local'\n]);\n\nconsole.log(typeof variables, variables); // \u003e object { FOO: 'bar', BAZ: 'qux' }\n```\n\n\n#### `.load(filenames, [options]) =\u003e object`\n\nLoads variables defined in a given file(s) into `process.env`.\n\nWhen several filenames are given, parsed environment variables are merged using the \"overwrite\" strategy since it utilizes [`.parse()`](#parsefilenames-options--object) for doing this.\nBut eventually, assigning the parsed environment variables to `process.env` is done using the \"append\" strategy, thus giving a higher priority to the environment variables predefined by the shell.\n\n\n##### Parameters:\n\n##### `filenames`\n###### Type: `string|string[]`\n\nA filename or a list of filenames to load.\n\n##### `options.encoding`\n###### Type: `string`\n###### Default: `\"utf8\"`\n\nAn optional encoding for reading files.\n\n##### `options.debug`\n###### Type: `boolean`\n###### Default: `false`\n\nOptionally, turn on debug messages.\n\n##### `options.silent`\n###### Type: `boolean`\n###### Default: `false`\n\nIf enabled, suppresses all kinds of warnings including \".env*\" files' loading errors.\n\n##### Returns:\n\n###### Type: `object`\n\nThe same as `.config()`, the returning object contains\n`.parsed` property with a parsed content of the given file(s),\nor if parsing is failed the `.error` property with a reference\nto the reasoning error.\n\n##### Example:\n\n```sh\n# .env\n\nFOO=bar\nBAZ=bar\n```\n\n```sh\n# .env.local\n\nBAZ=qux\n```\n\n```js\nconst dotenvFlow = require('dotenv-flow');\n\nprocess.env.BAZ = 'Yay!';\n\nconst result = dotenvFlow.load([\n  '/path/to/project/.env',\n  '/path/to/project/.env.local'\n]);\n\nconsole.log(typeof result, result); // \u003e object { parsed: { FOO: 'bar', BAZ: 'qux' } }\n\nconsole.log(process.env.FOO); // \u003e 'bar'\nconsole.log(process.env.BAZ); // \u003e 'Yay!'\n```\n\n\n#### `.unload(filenames, [options]) =\u003e void`\n\nUnloads variables defined in a given file(s) from `process.env`.\n\nThe environment variables that are predefined (i.e. by the shell) will not be unloaded.\n\n\n##### Parameters:\n\n##### `filenames`\n###### Type: `string|string[]`\n\nA filename or a list of filenames to unload.\n\n##### `options.encoding`\n###### Type: `string`\n###### Default: `\"utf8\"`\n\nAn optional encoding for reading files.\n\n\n##### Example:\n\n```sh\n# .env\n\nFOO=bar\nBAZ=bar\n```\n\n```sh\n# .env.local\n\nBAZ=qux\n```\n\n```js\nconst dotenvFlow = require('dotenv-flow');\n\nprocess.env.BAZ = 'Yay!';\n\ndotenvFlow.load([\n  '/path/to/project/.env',\n  '/path/to/project/.env.local'\n]);\n\nconsole.log(process.env.FOO); // \u003e 'bar'\nconsole.log(process.env.BAZ); // \u003e 'Yay!'\n\ndotenvFlow.unload([\n  '/path/to/project/.env',\n  '/path/to/project/.env.local'\n]);\n\nconsole.log(process.env.FOO); // \u003e undefined\nconsole.log(process.env.BAZ); // \u003e 'Yay!'\n```\n\n---\n\n\n## Related packages\n\n* [`@types/dotenv-flow`](https://www.npmjs.com/package/@types/dotenv-flow) – type definitions for using `dotenv-flow` with TypeScript\n* [`dotenv-flow-webpack`](https://github.com/kerimdzhanov/dotenv-flow-webpack) – a webpack plugin for using `dotenv-flow` in web applications\n* [`dotenv-flow-cli`](https://github.com/ovos/dotenv-flow-cli) – CLI executable that preloads environment variables using `dotenv-flow`\n* [`dotenv-expand`](https://github.com/motdotla/dotenv-expand) – environment variables expansion _(originally designed for `dotenv`, but also compatible with `dotenv-flow`)_\n\n\n## Contributing\n\nFeel free to dive in! [Open an issue](https://github.com/kerimdzhanov/dotenv-flow/issues/new) or submit PRs.\n\n\n## Running tests\n\nUsing NPM:\n\n```sh\n$ npm test\n```\n\nUsing Yarn:\n\n```sh\n$ yarn test\n```\n\n\n## License\n\nLicensed under [MIT](LICENSE) © 2018-2023 Dan Kerimdzhanov\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkerimdzhanov%2Fdotenv-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkerimdzhanov%2Fdotenv-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkerimdzhanov%2Fdotenv-flow/lists"}