{"id":22362771,"url":"https://github.com/danmasta/env","last_synced_at":"2026-02-08T19:34:54.295Z","repository":{"id":25459696,"uuid":"100553760","full_name":"danmasta/env","owner":"danmasta","description":"Environment helper for node apps","archived":false,"fork":false,"pushed_at":"2024-12-07T05:46:28.000Z","size":330,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-30T15:25:05.669Z","etag":null,"topics":["config","dotenv","env","environment"],"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/danmasta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null}},"created_at":"2017-08-17T02:42:13.000Z","updated_at":"2024-12-07T05:46:32.000Z","dependencies_parsed_at":"2025-07-30T14:35:12.302Z","dependency_job_id":null,"html_url":"https://github.com/danmasta/env","commit_stats":{"total_commits":67,"total_committers":1,"mean_commits":67.0,"dds":0.0,"last_synced_commit":"dceb25774da703c1c57d488b2190cf5000cc766d"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/danmasta/env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danmasta","download_url":"https://codeload.github.com/danmasta/env/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fenv/sbom","scorecard":{"id":321243,"data":{"date":"2025-08-11","repo":{"name":"github.com/danmasta/env","commit":"e64e2fea42ffa10c90445932b0dbf661cd6f6e0e"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.3,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":10,"reason":"21 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-18T01:24:44.272Z","repository_id":25459696,"created_at":"2025-08-18T01:24:44.272Z","updated_at":"2025-08-18T01:24:44.272Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29240704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T18:06:38.086Z","status":"ssl_error","status_checked_at":"2026-02-08T18:06:09.124Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["config","dotenv","env","environment"],"created_at":"2024-12-04T17:11:41.863Z","updated_at":"2026-02-08T19:34:54.289Z","avatar_url":"https://github.com/danmasta.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Env\nEnvironment helper for node apps\n\n#### Features:\n* Easy to use\n* Load `.env`, `.js`, `.json`, `.cjs`, or `.mjs` files\n* [Type coercion](#type-coercion) for primitive types\n* Option for setting helper variables like `NODE_ENV`\n* Optional command line helper `--env` for defining variables from argv\n* Source of truth is always `process.env`\n* Will not override existing variables\n* Bash-like [variable expansion](#variable-expansion) via `$var` or `${var}`\n* Full [character escape sequence](#escape-sequences) support (unicode, hex, octal, single)\n* Start of line and end of line [comments](#comments) are supported\n* Support for multiline values\n* Support for loading variables from [vault](#load-variables-from-vault)\n* Native ESM and CJS support\n* 0 external dependencies\n\n## About\nI wanted a better way to interact with environment variables in node apps. This package aims to simplify the process while maintaining `process.env` as the source of truth. It can parse variables from `.env`, `.js`, `.json`, `.cjs`, or `.mjs` files, and it can also import variables from [vault](https://github.com/hashicorp/vault) secrets. It supports type casting so you can use variables with boolean or number values as their native types. Variable expansion, multiline values, comments, and full character escape sequences are also supported.\n\n## Usage\nAdd env as a dependency for your app and install via npm\n```sh\nnpm install env@danmasta/env --save\n```\nInstall a specific [version](https://github.com/danmasta/env/tags)\n```\nnpm install env@danmasta/env#(tag|commit) --save\n```\n\nImport or require the package in your app\n```js\nimport env from 'env';\n```\n\nGet an environment variable\n```js\nenv('NODE_ENV');\n```\n\nSet an environment variable\n```js\nenv('NODE_ENV', 'development');\n```\n### Options\nName | Type | Description\n-----|------|------------\n`setArgv` | *`boolean`* | Set variables from argv. Used in `resolve` fns. Default is `false`\n`argv` | *`string\\|string[]\\|object`* | Value to use for parsing argv. Default is `undefined`\n`setNodeEnv` | *`boolean`* | Set the `NODE_ENV` variable if not already set. Default is `false`\n`nodeEnv` | *`string`* | Value to use if `setNodeEnv` is enabled. Default is `'development'`\n`helpers` | *`string\\|string[]`* | List of helper variables to add if `setNodeEnv` is enabled. Default is `['DEVELOPMENT', 'PRODUCTION']`\n`files` | *`string\\|string[]`* | File paths to load variables from. Default is: `['./.env', './config/.env', './env.js', './config/env.js']`\n`dir` | *`string`* | Directory to resolve relative paths from. Default is `undefined`\n`exts` | *`string\\|string[]`* | Supported file extensions to use during file lookup. Default is `['.js', '.json', '.cjs', '.mjs']`\n`encoding` | *`string`* | Encoding to use when reading `.env` files. Default is `'utf8'`\n`native` | *`boolean`* | Convert values to native types when reading variables. Default is `true`\n`replace` | *`boolean`* | Replace `undefined` variables during expansion. Default is `true`\n`def` | *`string`* | Value to use for `undefined` variables during expansion. Default is `''`\n`secret` | *`string`* | Secret path to use when loading variables from vault. Default is `undefined`\n`token` | *`string`* | Auth token to use when loading variables from vault. Default is `undefined`\n`addr` | *`string`* | Server address to use when loading variables from vault. Default is `undefined`\n`timeout` | *`number`* | Timeout in milliseconds to use when loading variables from vault. Default is `2500`\n`silent` | *`boolean`* | Disable error output. Default is `true`\n`warn` | *`boolean`* | Write errors to `stderr` instead of throwing. Default is `false`\n`overwrite` | *`boolean`* | Overwrite variables if they already exist. Used in all methods that call `set`. Default is `false`\n---\n\n### Methods\nName | Description\n-----|------------\n`get(key, opts?)` | Get a value from `process.env`. Will convert to native type if enabled\n`set(key, val?, opts?)` | Set a value on `process.env`\n`env(key, val?, opts?)` | Getter/setter. Proxies to `get` and `set` based on arguments signature\n`loadFromArgv(opts?)` | Load variables from argv\n`loadFromFiles(opts?)` | Load variables from files asynchronously\n`loadFromFilesSync(opts?)` | Load variables from files synchronously\n`loadFromVault(secret?, opts?)` | Load variables from a [vault](https://github.com/hashicorp/vault) secret asynchronously. Default timeout is `2.5 seconds`\n`loadFromVaultSync(secret?, opts?)` | Load variables from a [vault](https://github.com/hashicorp/vault) secret synchronously. This method creates a network request using a synchronous worker thread which will block the main thread until complete. Default timeout is `2.5 seconds`\n`resolve(opts?)` | Load variables asynchronously. Optionally load from argv and set helpers\n`resolveSync(opts?)` | Load variables synchronously. Optionally load from argv and set helpers\n`setHelpers(opts?)` | Set `NODE_ENV` and helper variables\n---\n\n## Environment Files\nBy default this package will attempt to load environment files in the following order:\n1. `.env`\n2. `config/.env`\n3. `env.(js|json|cjs|mjs)`\n4. `config/env.(js|json|cjs|mjs)`\n\n*Note: If multiple files are found, they do not overwrite each other. This package respects the first value set for each key*\n\n## Type Coercion\nWhen values are set on `process.env` they are always converted to a string. This can make it awkward when using boolean values or other primitive types. When getting a variable using this package, it will attempt to convert the value back to it's native type if desired. This includes: `true`, `false`, `null`, `undefined`, `NaN`, and `number`.\n\n## Escape Sequences\nAll escape sequences defined [here](https://mathiasbynens.be/notes/javascript-escapes) are supported, including unicode code points, unicode escapes, hexidecimal escapes, octal escapes, and single character escapes.\n\nJust use regular escape code format for values with escape sequences: `\\u{1d306}`, `\\u2665`, `\\xA5`, `\\001`, `\\n`, `\\t`, etc.\n\n## Variable Expansion\nBash-like variable expansion is supported in `.env` files. Just prefix a variable name with a `$` sign or wrap it in `${var}`. If you need to escape the `$` sign just use regular escape format like other sequences: `\\$`.\n```sh\nHOST=127.0.0.1\nPORT=6379\nREDIS_URL=redis://$HOST:$PORT\nESCAPED=\\$ESCAPED\n```\n\n## Helper Options\nThere are a few helper options you can use to set `NODE_ENV` and parse variables from `argv`:\n```js\nimport { setHelpers } from 'env';\n\nawait setHelpers({\n    nodeEnv: 'development',\n    helpers: ['DEVELOPMENT', 'PRODUCTION']\n});\n```\nOr you can do it all at the same time with `resolve`:\n```js\nimport { resolve } from 'env';\n\nawait resolve({\n    setArgv: true\n    setNodeEnv: true,\n    ...opts\n});\n```\nThis will enable CLI arguments for setting environment variables when running your app:\n```sh\nnode app --node-env=local --env=REDIS_HOST=127.0.0.1,REDIS_PORT=6379\n```\nThe other helper variables are also added. They become boolean values which will be `true` if `NODE_ENV` matches their variable name, otherwise `false`.\n\n## Comments\nStart of line and end of line comments are supported:\n```sh\n# Redis config\nHOST=127.0.0.1\nPORT=6379\nREDIS_URL=redis://$HOST:$PORT # Redis URL\n```\nIf you want to use the `#` symbol in a string, just wrap the string in single or double quotes:\n```sh\nTEST=\"This #comment will be ignored\"\n```\n\n## Load Additional Files\nIf you want to load variables from other files programatically you can use the `loadFromFiles` and `loadFromFilesSync` methods:\n```js\nimport { loadFromFiles } from 'env';\n\nawait loadFromFiles({\n    files: './config/production/.env'\n});\n```\n*Note: Home character expansion (`~`) is also supported.*\n\n## Load Variables from [Vault](https://github.com/hashicorp/vault)\nThis package also supports loading environment variables from vault. It will attempt to read the variables from a vault secret path, then parse the key/value pairs and set them in the environment. The vault api HTTP requests can be made asynchronously, or synchronously via a worker thread that has a default timeout of `2.5 seconds`.\n```js\nimport { loadFromVault } from 'env';\n\nlet token = '$VAULT_TOKEN';\nlet addr = '$VAULT_ADDR';\n\nawait loadFromVault('/env/app/prod', { token, addr });\n```\nThe secret, token, and addr params can be set explicity when calling the function, or can be set as defaults when creating an env instance. It will also read from the `VAULT_TOKEN` and `VAULT_ADDR` [environment variables](https://www.vaultproject.io/docs/commands#environment-variables), as well as the default [token helper](https://www.vaultproject.io/docs/commands#token-helper) file location: `~/.vault-token`.\n\n*Note: When loading secrets from vault, the api path is slightly [different](https://developer.hashicorp.com/vault/docs/secrets/kv#version-comparison) for `kv v1` vs `kv v2 (versioned)` secrets*\n\n### Example\nIf you had a `kv v1` secret mount point of `/env` and you wanted to load the secret path `/app/prod`, you could use the whole path as-is:\n```js\nawait loadFromVault('/env/app/prod');\n```\nHowever, with `kv v2`, you need to append `/data` to the mount point. The above example would become:\n```js\nawait loadFromVault('/env/data/app/prod');\n```\n\n### Sync\nIf your app still uses `CJS` and/or doesn't support top level `await` and you need to load variables from vault synchronously, you can do that too:\n```js\nconst { loadFromVaultSync } = require('env');\n\nloadFromVaultSync('/env/app/prod');\n```\n\n## Examples\n#### Get an environment variable\n```js\nenv('NODE_ENV');\n```\n\n#### Set an environment variable\n```js\nenv('NODE_ENV', 'development');\n```\n\n#### Set multiple environment variables\n```js\nenv({\n    REDIS_HOST: '127.0.0.1',\n    REDIS_PORT: 6379\n});\n```\n\n#### Load extra environment files\n```js\nimport { loadFromFiles } from 'env';\n\nawait loadFromFiles({\n    files: './config/production/.env'\n});\n```\n\n#### Load environment variables from vault\n```sh\nexport VAULT_TOKEN=\"$TOKEN\"\nexport VAULT_ADDR=\"https://vault.example.net\"\n```\n```js\nawait loadFromVault('/env/app/prod');\n```\n\n#### ESM\nIf using ESM for your config, you can export env variables as a default export or named exports:\n```js\nexport default {\n    REDIS_HOST: '127.0.0.1',\n    REDIS_PORT: 6379\n};\n```\n```js\nexport const REDIS_HOST = '127.0.0.1';\nexport const REDIS_PORT = 6379;\n```\n*Note: If both a default export and named exports are found, default export will take precedence*\n\n#### Load env variables dynamically from vault based on config settings\nIf you use a [config](https://github.com/danmasta/config) library that supports loading `js` files, you can use this package to dynamically load environment variables based on your config settings:\n```js\n---\n// config/local.js\nimport { loadFromVault } from 'env';\n\nawait loadFromVault('/env/app/local');\n\nexport default {\n    ...\n};\n---\n// config/development.js\nimport { loadFromVault } from 'env';\n\nawait loadFromVault('/env/app/dev');\n\nexport default {\n    ...\n};\n---\n// config/production.js\nimport { loadFromVault } from 'env';\n\nawait loadFromVault('/env/app/prod');\n\nexport default {\n    ...\n};\n---\n// app.js\nimport env from 'env';\nimport config from 'config';\n\napp.listen(env('PORT'));\n---\n```\n\n#### Check if environment is `development` using helper variable\n```js\n// true if NODE_ENV === 'development'\nenv('DEVELOPMENT');\n```\n\n#### Check if environment is `production` using helper variable\n```js\n// true if NODE_ENV === 'production'\nenv('PRODUCTION');\n```\n\n## Testing\nTests are currently run using mocha and chai. To execute tests run `make test`. To generate unit test coverage reports run `make coverage`\n\n## Contact\nIf you have any questions feel free to get in touch\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanmasta%2Fenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanmasta%2Fenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanmasta%2Fenv/lists"}