{"id":14156057,"url":"https://github.com/adonisjs/env","last_synced_at":"2026-02-25T07:24:34.454Z","repository":{"id":34896259,"uuid":"186640446","full_name":"adonisjs/env","owner":"adonisjs","description":"Framework agnostic environment variables parser and validator","archived":false,"fork":false,"pushed_at":"2025-12-15T04:21:03.000Z","size":473,"stargazers_count":45,"open_issues_count":0,"forks_count":11,"subscribers_count":5,"default_branch":"7.x","last_synced_at":"2025-12-17T01:28:41.786Z","etag":null,"topics":["bundled-with-core","env"],"latest_commit_sha":null,"homepage":"https://docs.adonisjs.com/guides/environment-variables","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/adonisjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"thetutlage"}},"created_at":"2019-05-14T14:32:47.000Z","updated_at":"2025-12-15T04:21:07.000Z","dependencies_parsed_at":"2024-04-27T23:27:37.697Z","dependency_job_id":"b75f9edf-f0a4-46f1-b174-0c045eeed740","html_url":"https://github.com/adonisjs/env","commit_stats":{"total_commits":143,"total_committers":9,"mean_commits":15.88888888888889,"dds":0.09090909090909094,"last_synced_commit":"ad2f14d4261cb325cf71459fcd4609fa7e010edd"},"previous_names":["poppinss/env"],"tags_count":70,"template":false,"template_full_name":null,"purl":"pkg:github/adonisjs/env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonisjs%2Fenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonisjs%2Fenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonisjs%2Fenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonisjs%2Fenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adonisjs","download_url":"https://codeload.github.com/adonisjs/env/tar.gz/refs/heads/7.x","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonisjs%2Fenv/sbom","scorecard":{"id":167471,"data":{"date":"2025-08-11","repo":{"name":"github.com/adonisjs/env","commit":"5b957ef0d3c29531f33bdf2961a60d1a4a50f125"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.2,"checks":[{"name":"Code-Review","score":1,"reason":"Found 3/25 approved changesets -- score normalized to 1","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":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"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":"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":"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":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","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":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: third-party GitHubAction not pinned by hash: .github/workflows/checks.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/adonisjs/env/checks.yml/6.x?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/checks.yml:9: update your workflow using https://app.stepsecurity.io/secureworkflow/adonisjs/env/checks.yml/6.x?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/checks.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/adonisjs/env/checks.yml/6.x?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/labels.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/adonisjs/env/labels.yml/6.x?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/labels.yml:11: update your workflow using https://app.stepsecurity.io/secureworkflow/adonisjs/env/labels.yml/6.x?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/adonisjs/env/release.yml/6.x?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/adonisjs/env/release.yml/6.x?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/stale.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/adonisjs/env/stale.yml/6.x?enable=pin","Warn: npmCommand not pinned by hash: .github/workflows/release.yml:28","Info:   0 out of   4 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   4 third-party GitHubAction dependencies pinned","Info:   0 out of   1 npmCommand dependencies pinned"],"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":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/checks.yml:1","Warn: topLevel 'contents' permission set to 'write': .github/workflows/release.yml:4","Warn: no topLevel permission defined: .github/workflows/stale.yml:1","Info: no jobLevel write permissions found"],"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":"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":"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"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.md:0","Info: FSF or OSI recognized license: MIT License: LICENSE.md:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: github.com/adonisjs/.github/docs/SECURITY.md:1","Info: Found linked content: github.com/adonisjs/.github/docs/SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: github.com/adonisjs/.github/docs/SECURITY.md:1","Info: Found text in security policy: github.com/adonisjs/.github/docs/SECURITY.md:1"],"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":"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":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch '6.x'","Warn: branch protection not enabled for branch 'develop'"],"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":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 8 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-16T15:18:52.277Z","repository_id":34896259,"created_at":"2025-08-16T15:18:52.277Z","updated_at":"2025-08-16T15:18:52.277Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29811531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T03:30:18.102Z","status":"ssl_error","status_checked_at":"2026-02-25T03:30:17.799Z","response_time":61,"last_error":"SSL_read: 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":["bundled-with-core","env"],"created_at":"2024-08-17T08:05:11.271Z","updated_at":"2026-02-25T07:24:34.411Z","avatar_url":"https://github.com/adonisjs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/thetutlage"],"categories":["others"],"sub_categories":[],"readme":"# @adonisjs/env\n\u003e Environment variables parser and validator used by the AdonisJS.\n\n[![gh-workflow-image]][gh-workflow-url] [![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]\n\n\u003e **Note:** This package is framework agnostic and can also be used outside of AdonisJS.\n\nThe `@adonisjs/env` package encapsulates the workflow around loading, parsing, and validating environment variables.\n\n## Setup\nInstall the package from the npm packages registry as follows.\n\n```sh\nnpm i @adonisjs/env\n```\n\n## EnvLoader\nThe `EnvLoader` class is responsible for loading the environment variable files from the disk and returning their contents as a string.\n\n```ts\nimport { EnvLoader } from '@adonisjs/env'\n\nconst lookupPath = new URL('./', import.meta.url)\nconst loader = new EnvLoader(lookupPath)\n\nconst envFiles = await loader.load()\n```\n\nThe return value is an array of objects with following properties.\n\n- `path`: The path to the loaded dot-env file.\n- `contents`: The contents of the file.\n\nFollowing is the list of loaded files. The array is ordered by the priority of the files. The first file has the highest priority and must override the variables from the last file.\n\n| Priority | File name | Environment | Should I `.gitignore` it | Notes |\n|----------|-----------|-------------|--------------------------|-------|\n| 1st | `.env.[NODE_ENV].local` | Current environment | Yes | Loaded when `NODE_ENV` is set |\n| 2nd | `.env.local` | All | Yes | Loaded in all the environments except `test` or `testing` environments |\n| 3rd | `.env.[NODE_ENV]` | Current environment | No | Loaded when `NODE_ENV` is set |\n| 4th | `.env` | All | Depends | Loaded in all the environments. You should `.gitignore` it when storing secrets in this file |\n\n## EnvParser\nThe `EnvParser` class is responsible for parsing the contents of the `.env` file(s) and converting them into an object.\n\n```ts\nimport { EnvParser } from '@adonisjs/env'\nconst envParser = new EnvParser(`\n  PORT=3000\n  HOST=localhost\n`)\n\nconsole.log(await envParser.parse()) // { PORT: '3000', HOST: 'localhost' }\n```\n\nThe return value of `parser.parse` is an object with key-value pair. The parser also has support for interpolation.\n\nBy default, the parser prefers existing `process.env` values when they exist. However, you can instruct the parser to ignore existing `process.env` files as follows.\n\n```ts\nnew EnvParser(envContents, { ignoreProcessEnv: true })\n```\n\n### Identifier\n\nYou can define an \"identifier\" to be used for interpolation. The identifier is a string that prefix the environment variable value and let you customize the value resolution.\n\n```ts\nimport { readFile } from 'node:fs/promises'\nimport { EnvParser } from '@adonisjs/env'\n\nEnvParser.identifier('file', (value) =\u003e {\n  return readFile(value, 'utf-8')\n})\n\nconst envParser = new EnvParser(`\n  DB_PASSWORD=file:/run/secret/db_password\n`)\n\nconsole.log(await envParser.parse()) // { DB_PASSWORD: 'Value from file /run/secret/db_password' }\n```\n\nThis can be useful when you are using secrets manager like `Docker Secret`, `HashiCorp Vault`, `Google Secrets Manager` and others to manage your secrets.\n\n## Validating environment variables\nOnce you have the parsed objects, you can optionally validate them against a pre-defined schema. We recommend validation for the following reasons.\n\n- Fail early if one or more environment variables are missing.\n- Cast values to specific data types. \n- Have type safety alongside runtime safety.\n\n```ts\nimport { Env } from '@adonisjs/env'\n\nconst validator = Env.rules({\n  PORT: Env.schema.number(),\n  HOST: Env.schema.string({ format: 'host' })\n})\n```\n\nThe `Env.schema` is a reference to the [@poppinss/validator-lite](https://github.com/poppinss/validator-lite) `schema` object. Make sure to go through the package README to view all the available methods and options.\n\nThe `Env.rules` method returns an instance of the validator to validate the environment variables. The return value is the validated object with type information inferred from the schema.\n\n```ts\nvalidator.validate(process.env)\n```\n\n## Complete example\n\nFollowing is a complete example of loading dot-env files and validating them in one go.\n\n\u003e **Note**: Existing `process.env` variables have the top most priority over the variables defined in any of the files.\n\n```ts\nimport { Env } from '@adonisjs/env'\n\nconst env = await Env.create(new URL('./', import.meta.url), {\n  PORT: Env.schema.number(),\n  HOST: Env.schema.string({ format: 'host' })\n})\n\nenv.get('PORT') // is a number\nenv.get('HOST') // is a string\nenv.get('NODE_ENV') // is unknown, hence a string or undefined\n```\n\n## Env editor\nThe Env editor can be used to edit dot-env files and persist changes on disk. Only the `.env` and `.env.example` files are updated (if exists).\n\n```ts\nimport { EnvEditor } from '@adonisjs/env/editor'\n\nconst editor = await EnvEditor.create(new URL('./', import.meta.url))\neditor.add('PORT', 3000)\neditor.add('HOST', 'localhost')\n\n// Write changes on disk\nawait editor.save()\n```\n\nYou can also insert an empty value for the `.env.example` file by setting the last argument to `true`.\n\n```ts\neditor.add('SECRET_VARIABLE', 'secret-value', true)\n```\n\nThis will add the following line to the `.env.example` file.\n\n```env\nSECRET_VARIABLE=\n```\n\n## Known Exceptions\n\n### E_INVALID_ENV_VARIABLES\nThe exception is raised during environment variables validation exception. The exception is raised with `Validation failed for one or more environment variables` message.\n\nYou can access the detailed error messages using the `error.cause` property.\n\n```ts\ntry {\n  validate(envValues)\n} catch (error) {\n  console.log(error.cause)\n}\n```\n\n[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/env/checks.yml?style=for-the-badge\n[gh-workflow-url]: https://github.com/adonisjs/env/actions/workflows/checks.yml \"Github action\"\n\n[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge\u0026logo=typescript\n[typescript-url]:  \"typescript\"\n\n[npm-image]: https://img.shields.io/npm/v/@adonisjs/env.svg?style=for-the-badge\u0026logo=npm\n[npm-url]: https://npmjs.org/package/@adonisjs/env \"npm\"\n\n[license-image]: https://img.shields.io/npm/l/@adonisjs/env?color=blueviolet\u0026style=for-the-badge\n[license-url]: LICENSE.md \"license\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadonisjs%2Fenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadonisjs%2Fenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadonisjs%2Fenv/lists"}