{"bugs":{"url":"https://github.com/kerimdzhanov/dotenv-flow/issues"},"dist":{"shasum":"d79ca1051227bb3410c2dbe8d46e8b9223a624e0","tarball":"https://registry.npmjs.org/dotenv-flow/-/dotenv-flow-3.3.0-rc.1.tgz","fileCount":10,"integrity":"sha512-SmcBs19CRRzYIj8ncVhsaPsNCmWJKiDv+n4Ajbzh5sR7i4lyRQoVoJWedBrjw4GeqCjW4cB0+ku5NNbRhjMN7g==","signatures":[{"sig":"MEUCIFeE6ZmkkoOsokgEtaWe59MYsP1v+1BefgwUmHedbITUAiEAjUYxYavUwlYbJCTf/D3+6SniSw0Y+FzjF25qJMvsdT4=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":34993},"main":"lib/dotenv-flow.js","name":"dotenv-flow","author":{"name":"Dan Kerimdzhanov"},"readme":"# dotenv-flow [](https://badge.fury.io/js/dotenv-flow)\n\n![\"dotenv-flow\"](\"https://raw.githubusercontent.com/kerimdzhanov/dotenv-flow/master/dotenv-flow@2x.png\")
\n\n[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 the ability to have multiple `.env*` files like `.env.development`, `.env.test` and `.env.production`, also allowing defined variables to be overwritten individually in the appropriate `.env*.local` file.\n\nStoring configuration in _environment variables_ separate from code and grouping them by environments like _development_, _test_ and _production_ is based on [The Twelve-Factor App](https://12factor.net/config) methodology.\n\n[](https://github.com/kerimdzhanov/dotenv-flow/actions/workflows/ci.yml)\n[](https://snyk.io/test/github/kerimdzhanov/dotenv-flow?targetFile=package.json)\n[](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\n\n## Usage\n\nAs early as possible in your application, require and configure **dotenv-flow**.\n\n```js\nrequire('dotenv-flow').config();\n```\n\nAfter this, you can access all the environment variables you have defined in your `.env*` files through `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> SET NODE_ENV=production\n> 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\nWhen preloading **dotenv-flow** using the node's `-r` switch you can use the following configuration options:\n\n### Environment variables\n\n* `NODE_ENV` => [`options.node_env`](#optionsnode_env);\n* `DEFAULT_NODE_ENV` => [`options.default_node_env`](#optionsdefault_node_env);\n* `DOTENV_FLOW_PATH` => [`options.path`](#optionspath);\n* `DOTENV_FLOW_ENCODING` => [`options.encoding`](#optionsencoding);\n* `DOTENV_FLOW_PURGE_DOTENV` => [`options.purge_dotenv`](#optionspurge_dotenv);\n* `DOTENV_FLOW_SILENT` => [`options.silent`](#optionssilent);\n\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` => [`options.node_env`](#optionsnode_env);\n* `--default-node-env` => [`options.default_node_env`](#optionsdefault_node_env);\n* `--dotenv-flow-path` => [`options.path`](#optionspath);\n* `--dotenv-flow-encoding` => [`options.encoding`](#optionsencoding);\n* `--dotenv-flow-purge-dotenv` => [`options.purge_dotenv`](#optionspurge_dotenv);\n* `--dotenv-flow-silent` => [`options.silent`](#optionssilent);\n\nDon't forget to separate **dotenv-flow/config**-specific CLI switches with `--` because they are not recognized by **Node.js**:\n\n```sh\n$ node -r dotenv-flow/config your_script.js -- --dotenv-flow-encoding=latin1 --dotenv-flow-path=...\n```\n\n\n## API reference\n\n#### `.config([options]) => object`\n\nThe main entry point function that parses the contents of your `.env*` files, merges the results and appends to `process.env.*`.\n\nAlso, like the original module ([dotenv](https://github.com/motdotla/dotenv)), it returns an `object` with the `parsed` property containing the resulting key/values or the `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.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.silent`\n###### Type: `boolean`\n###### Default: `false`\n\nWith this option you can suppress all the console outputs except errors and deprecation warnings.\n\n```js\nrequire('dotenv-flow').config({\n silent: true\n});\n```\n\n---\n\nThe following API considered as internal, but it is also exposed to give the ability to be used programmatically by your own needs.\n\n\n#### `.listDotenvFiles(dirname, [options]) => string[]`\n\nReturns a list of `.env*` filenames depending on the given `options.node_env`. The resulting list is ordered by the env files priority from lowest to highest.\n\nAlso, note that the `.env.local` file will not be listed for `NODE_ENV=\"test\"`, since normally you expect tests to produce the same results for everyone.\n\n\n##### Parameters:\n\n##### `dirname`\n###### Type: `string`\n\nA path to `.env*` files' directory.\n\n##### `[options.node_env]`\n###### Type: `string`\n###### Default: _undefined_\n\nThe node environment (development/test/production/etc,).\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.listDotenvFiles('/path/to/project', { node_env: 'development' });\n\nconsole.log(filenames); // will output the following:\n// > [ '/path/to/project/.env',\n// > '/path/to/project/.env.local',\n// > '/path/to/project/.env.development',\n// > '/path/to/project/.env.development.local' ]\n```\n\n\n#### `.parse(filenames, [options]) => 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##### `[options.encoding]`\n###### Type: `string`\n###### Default: `\"utf8\"`\n\nAn optional encoding for reading files.\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); // > object { FOO: 'bar', BAZ: 'qux' }\n```\n\n\n#### `.load(filenames, [options]) => 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.silent]`\n###### Type: `boolean`\n###### Default: `false`\n\nSuppress all the console outputs except errors and deprecation warnings.\n\n##### Returns:\n\n###### Type: `object`\n\nThe returning object have the same shape as the `.config()`'s, it will contain the `parsed` property with a parsed content of a given file(s) or the `error` property if the parsing is failed.\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\nconst result = dotenvFlow.load([\n '/path/to/project/.env',\n '/path/to/project/.env.local'\n]);\n\nconsole.log(typeof result, result); // > object { parsed: { FOO: 'bar', BAZ: 'qux' } }\n\nconsole.log(process.env.FOO); // > 'bar'\nconsole.log(process.env.BAZ); // > 'Yay!'\n```\n\n\n#### `.unload(filenames, [options]) => 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); // > 'bar'\nconsole.log(process.env.BAZ); // > 'Yay!'\n\ndotenvFlow.unload([\n '/path/to/project/.env',\n '/path/to/project/.env.local'\n]);\n\nconsole.log(process.env.FOO); // > undefined\nconsole.log(process.env.BAZ); // > '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-2020 Dan Kerimdzhanov\n","engines":{"node":">= 8.0.0"},"exports":{".":"./lib/dotenv-flow.js","./config":"./config.js","./package.json":"./package.json"},"license":"MIT","scripts":{"test":"mocha -r mocha.conf.js test/{unit,integration}/*.spec.{m,}js","changelog":"conventional-changelog -p angular -i CHANGELOG.md -s"},"_npmUser":{"name":"kerimdzhanov","email":"kerimdzhanov@gmail.com"},"homepage":"https://github.com/kerimdzhanov/dotenv-flow#readme","keywords":["dotenv","node_env","development","test","production","local"],"repository":{"url":"git+https://github.com/kerimdzhanov/dotenv-flow.git","type":"git"},"description":"Loads environment variables from `.env.[development|test|production][.local]` files","directories":{},"licenseText":"Copyright (c) 2018-2019 Dan Kerimdzhanov \n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\nFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\nCOPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\nCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","maintainers":[{"name":"kerimdzhanov","email":"kerimdzhanov@gmail.com"}],"dependencies":{"dotenv":"^8.6.0"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"tmp":"^0.2.1","chai":"^4.3.7","mocha":"^10.2.0","sinon":"^15.2.0","sinon-chai":"^3.7.0","conventional-changelog-cli":"^2.0.35"},"_npmOperationalInternal":{"tmp":"tmp/dotenv-flow_3.3.0-rc.1_1692568196803_0.739979950475","host":"s3://npm-registry-packages"},"_id":"dotenv-flow@3.3.0-rc.1","version":"3.3.0-rc.1"}