{"id":17008164,"url":"https://github.com/szikszail/dotenv-ng","last_synced_at":"2025-04-12T07:21:17.304Z","repository":{"id":46594609,"uuid":"476344748","full_name":"szikszail/dotenv-ng","owner":"szikszail","description":"This tool is a custom implementation to handle .env files, inspired by dotenv (NPM) and python-dotenv (PyPi).","archived":false,"fork":false,"pushed_at":"2024-11-22T04:32:19.000Z","size":790,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T02:57:05.707Z","etag":null,"topics":["dotenv","env","environment","environment-variables","hacktoberfest"],"latest_commit_sha":null,"homepage":"https://dotenv-ng.6ai.lol","language":"TypeScript","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/szikszail.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":"2022-03-31T14:34:26.000Z","updated_at":"2024-11-22T04:31:58.000Z","dependencies_parsed_at":"2024-01-14T14:28:09.658Z","dependency_job_id":"7a36cdae-8088-4b6f-9a3f-34ef9955a9a3","html_url":"https://github.com/szikszail/dotenv-ng","commit_stats":{"total_commits":67,"total_committers":4,"mean_commits":16.75,"dds":"0.22388059701492535","last_synced_commit":"48045e496ba27a463fa78d4b88720546972cc989"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":"szikszail/npm-package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szikszail%2Fdotenv-ng","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szikszail%2Fdotenv-ng/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szikszail%2Fdotenv-ng/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szikszail%2Fdotenv-ng/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/szikszail","download_url":"https://codeload.github.com/szikszail/dotenv-ng/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248530761,"owners_count":21119626,"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":["dotenv","env","environment","environment-variables","hacktoberfest"],"created_at":"2024-10-14T05:27:34.879Z","updated_at":"2025-04-12T07:21:17.285Z","avatar_url":"https://github.com/szikszail.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dotenv-ng\n\n![Downloads](https://img.shields.io/npm/dw/dotenv-ng?style=flat-square) ![Version@npm](https://img.shields.io/npm/v/dotenv-ng?label=version%40npm\u0026style=flat-square) ![Version@git](https://img.shields.io/github/package-json/v/szikszail/dotenv-ng/main?label=version%40git\u0026style=flat-square) ![CI](https://img.shields.io/github/actions/workflow/status/szikszail/dotenv-ng/ci.yml?branch=main\u0026label=ci\u0026style=flat-square) ![Docs](https://img.shields.io/github/actions/workflow/status/szikszail/dotenv-ng/docs.yml?branch=main\u0026label=docs\u0026style=flat-square)\n\n![OS Windows](https://img.shields.io/badge/OS-Windows-green) ![OS Linux](https://img.shields.io/badge/OS-Linux-green) ![OS MacOS](https://img.shields.io/badge/OS-MacOS-green)\n\nThis tool is a custom implementation to handle `.env` files, inspired\nby [dotenv (NPM)](https://www.npmjs.com/package/dotenv)\nand [python-dotenv (PyPi)](https://pypi.org/project/python-dotenv/), including features like:\n\n- Handling simple `.env` file\n- Handling environment variable interpolation\n- Handling file hierarchy\n- Handling JavaScript literals\n\n## CLI\n\nThe tool contains a cross-platform command (`dotenv-ng`) that can be used to execute any command with environment\nvariables set, either explicitly in the command or from env-files or env-folders. The command supports all options of\nthe API (see below).\n\n### Install\n\n```shell\nnpm install -g dotenv-ng\n```\n\n### Usage\n\n```\ndotenv-ng [options] [--var KEY=value KEY=value ...] -- command\n\nOptions:\n  --version                Show version number                         [boolean]\n  --load                   The path of the env-file or the folder containing the\n                           env-files.                                   [string]\n  --environment            The environment-specific env-file to be loaded, if a\n                           folder is processed.                         \n                                  [string] [default: $DOTENVNG_ENV or $NODE_ENV]\n  --ignore-literal-case    Should the casing of special literals (e.g. true,\n                           false, null, undefined, NaN) be ignored?\n                                                       [boolean] [default: true]\n  --parse-literals         Should special literals be parsed as their JS values\n                           (e.g. true, false, null, undefined, NaN) or parsed as\n                           strings?                    [boolean] [default: true]\n  --parse-numbers          Should number literals be parsed as numbers or parsed\n                           as strings?                 [boolean] [default: true]\n  --allow-empty-variables  Should empty variables (without a value set) be\n                           allowed?                    [boolean] [default: true]\n  --allow-orphan-keys      Should orphan keys be allowed (line 24) or parsed as\n                           empty variables?           [boolean] [default: false]\n  --interpolation-enabled  Should string interpolation be evaluated for other\n                           environment variables or handled as literal strings?\n                                                       [boolean] [default: true]\n  --overwrite-existing     Should the existing environment variable values be\n                           overwritten?                [boolean] [default: true]\n  --normalize              Should the variable names be normalized (i.e. \n                           uppercase without white-space) and appended to the\n                           variables?                 [boolean] [default: false]\n  --var                    Case sensitive key=value pairs of the environment\n                           variables to be set.                          [array]\n  --help                   Show help                                   [boolean]\n\n- Either --load or one or more --var must be specified.\n- All boolean attributes have a --no version to set them to false, e.g.\n--no-overwrite-existing.\n- When a quoted argument is passed to the command itself, then the whole command\nmust be quoted.\n- The environment value is determined in order: \n    1. the --environment command line option, if set, otherwise\n    2. the DOTENVNG_ENV environment variable's value, if set, otherwise\n    3. the NODE_ENV environment variable's value, if set, otherwise\n    4. nothing.\n```\n\n#### PowerShell\n\nAs in **PowerShell**, the `--` separator is interpreted differently, the command also accepts the `---` separator.\n\n## API\n\n### Environment files\n\nYou can define a `.env` file containing configuration, and environment variables, with\n\n- A simple number, string, or boolean values\n- Comments\n- Environment variables interpolation\n\n```sh\n# .env\n# This is an environment file (simplified)\nexport EXPORTED_VARIABLE=simple value # this will be a string\nexport OTHER_EXPORTED_VARIABLE=123 # this will be a number\n# You can leave the export statement and set\n# just key-value pairs\nSIMPLE_STRING_VARIABLE = \"hello world\" # string can be also set in quotes\nOTHER_STRING_VARIABLE = 'hello world' # or apostrophes\nSIMPLE_NUMBER_VARIABLE = 1\n# Boolean variables can have true,false values\nSIMPLE_BOOLEAN_VARIABLE = false\nOTHER_BOOLEAN_VARIABLE = true\nOTHER_CASE_BOOLEAN_VARIABLE = TRUE\n# String interpolation will also wrok\n# with the ${KEY} format\nINTERPOLATED_VARIABLE = \"this is also ${SIMPLE_STRING_VARIABLE}\"\nOTHER_BUT_NOT_INTERPOLATED = \"this won't work $SIMPLE_STRING_VARIABLE (for now)\" # this won't work yet\nINTERPOLATED_WITH_SYSVARS = \"system temp: ${JAVA_HOME}\" # use environment variables\n# We suggest following the standard naming conventions\n# for environment variables (CAPITALS with _)\n# but others will work as well\nthis is also an environment variable = \"with this value\"\n# These lines are ignored, without =, or without key\nTHIS_WILL_BE_IGNORED\n=\"this as well.\"\n# This will be an empty variable (empty string)\nEMPTY_VARIABLE=\n# Special values are also supported\nNULL_VARIABLE=null\nOTHER_NULL_VARIABLE=NULL\nUNDEFINED_VARIABLE=undefined\nOTHER_UNDEFINED_VARIABLE=UNDEFINED\nLITERAL_NULL_VARIABLE=\"null\" # to use these particular values as strings set them as a string\n# A variable can be set optional, by using\n# the ?= instead of the = sign. In this case\n# the variable will be set only if it is not already\n# set during parsing, even if overwriteExisting is set.\nSOME_KEY ?= SOME DEFAULT VALUE\n```\n\n### Install\n\n```shell\nnpm install dotenv-ng --save\n```\n\n### Parsing\n\nAn environment file can be parsed with the `parse` function. This will parse the valid values and the parsing errors as\nwell.\n\n```typescript\nimport {parse} from \"dotenv-ng\"\n\nconst results = parse(\".env\")\nconsole.log(results.data);\n// {\n//   \"EXPORTED_VARIABLE\": \"simple value\",\n//   \"OTHER_EXPORTED_VARIABLE\": 123,\n//   \"SIMPLE_STRING_VARIABLE\": \"hello world\",\n//   \"OTHER_STRING_VARIABLE\": \"hello world\",\n//   \"SIMPLE_NUMBER_VARIABLE\": 1,\n//   \"SIMPLE_BOOLEAN_VARIABLE\": false,\n//   \"OTHER_BOOLEAN_VARIABLE\": true,\n//   \"OTHER_CASE_BOOLEAN_VARIABLE\": true,\n//   \"INTERPOLATE_VARIABLE\": \"this is also hello world\",\n//   \"OTHER_BUT_NOT_INTERPOLATED\": \"this won't work $SIMPLE_STRING_VARIABLE (for now)\",\n//   \"INTERPOLATED_WITH_SYSVARS\": \"sytem temp: C:\\\\bin\\\\java\",\n//   \"this is also an environment variable\": \"with this value\",\n//   \"EMPTY_VARIABLE\": \"\",\n//   \"NULL_VARIABLE\": null,\n//   \"OTHER_NULL_VARIABLE\": null,\n//   \"UNDEFINED_VARIABLE\": undefined,\n//   \"OTHER_UNDERFINED_VARIABLE: undefined,\n//   \"LITERAL_NULL_VARIABLE\": \"null\",\n//   \"SOME_KEY\": \"SOME DEFAULT VALUE\"\n// }\n\nconsole.log(results.errors);\n// [\n//   { \"line\": 24, \"error\": \"ORPHAN_KEY\", \"data\": \"THIS_WILL_BE_IGNORED\" },\n//   { \"line\": 25, \"error\": \"MISSING_KEY\", \"data\": \"=\\\"this as well\\\"\" }\n// ]\nconsole.log(results.optional);\n// [\n//   \"SOME_KEY\"\n// ]\n```\n\n### Values\n\nTo retrieve the valid, parsed values, you can use the `values` function:\n\n```typescript\nimport {values} from \"dotenv-ng\";\n\nconst v = values(\".env\")\nconsole.log(v);\n\n// {\n//   \"EXPORTED_VARIABLE\": \"simple value\",\n//   \"OTHER_EXPORTED_VARIABLE\": 123,\n//   ...\n//   \"OTHER_UNDERFINED_VARIABLE: undefined,\n//   \"LITERAL_NULL_VARIABLE\": \"null\"\n//   \"SOME_KEY\": \"SOME DEFAULT VALUE\"\n// }\n```\n\n### Updating environment variables\n\nTo update the environment variables in the context of the script (`process.env`), you can use the `load` function:\n\n```typescript\nimport {load} from \"dotenv-ng\";\n\nload(\".env\");\nconsole.log(process.env);\n\n// {\n//   ...\n//   \"EXPORTED_VARIABLE\": \"simple value\",\n//   \"OTHER_EXPORTED_VARIABLE\": 123,\n//   ...\n//   \"OTHER_UNDERFINED_VARIABLE: undefined,\n//   \"LITERAL_NULL_VARIABLE\": \"null\"\n//   ...\n// }\n```\n\n### Overwrite\n\nBy default, `load` won't overwrite the existing environment variables, to enable it, set\nthe `overwriteExisting: boolean` configuration option:\n\n```typescript\nload(\".env\", {overwriteExisting: true})\n```\n\nIf `overwriteExisting` is disabled, then string interpolation in case of `parse` and `values` will **always** take the\nhost environment variable, even if it is redefined in the env-files (see [index.test.ts#l15](tests/index.test.ts#L15)).\n\n### Configuration\n\n`parse` (and other functions such as `load` and `values`) accepts an optional configuration to adjust parsing logic:\n\n| Option                 | Type      | Description                                                                                                                   | Default |\n|:-----------------------|:----------|:------------------------------------------------------------------------------------------------------------------------------|:--------|\n| `ingoreLiteralCase`    | `boolean` | Should the casing of special literals (e.g. `true`, `false`, `null`, `undefined`, `NaN`) be ignored.                          | `true`  |\n| `parseLiterals`        | `boolean` | Should special literals be parsed as their JS values (e.g. `true`, `false`, `null`, `undefined`, `NaN`) or parsed as strings. | `true`  |\n| `parseNumbers`         | `boolean` | Should number literals be parsed as numbers or parsed as strings.                                                             | `true`  |\n| `allowEmptyVariables`  | `boolean` | Should empty variables (without a values set) be allowed.                                                                     | `true`  |\n| `allowOrphanKeys`      | `boolean` | Should orphan keys be allowed (line 24) or parsed as empty variables.                                                         | `false` |\n| `interpolationEnabled` | `boolean` | Should string interpolation evaluated for other environment variables or handled as literal strings.                          | `true`  |\n| `overwriteExisting`    | `boolean` | Should the existing environment variable values be overwritten.                                                               | `false` |\n| `environment`          | `string`  | The environment specific environment file to be loaded, if a folder is processed.                                             | -       |\n| `normalize`            | `boolean` | Should the variable names be normalized (i.e. uppercase without white-space) and appended to the variables.                   | `false` |\n\nAll functions process the `.env` (or folder containing `.env` files) path and accept the configuration mentioned\npreviously.\n\n- If no path is passed to the function, the `.env` file in the current working directory will be processed\n- If a path to an environment file is passed to the function, that environment file is processed\n- If a path to a folder (that contains environment files) is passed to the function, all `.env*` files are processed,\n  and the combined results are returned.\n  The precedence of loading and combination is:\n    1. Default environment file (`.env`), if it exists\n    2. Environment specific environment file (e.g. `.env.development`), if set in the options and exists\n    3. Local environment file (`.env.local`), if it exists\n\n## Other\n\nFor detailed documentation see the [TypeDocs documentation](https://szikszail.github.io/dotenv-ng/).\n\nThis package uses [debug](https://www.npmjs.com/package/debug) for logging, use `dotenv-ng` to see debug logs:\n\n```shell\nDEBUG=dotenv-ng* node my-script.js\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszikszail%2Fdotenv-ng","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fszikszail%2Fdotenv-ng","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszikszail%2Fdotenv-ng/lists"}