{"id":13475039,"url":"https://github.com/rolodato/dotenv-safe","last_synced_at":"2025-05-14T10:12:47.207Z","repository":{"id":41344810,"uuid":"43795926","full_name":"rolodato/dotenv-safe","owner":"rolodato","description":"Load environment variables from .env and ensure they are all present","archived":false,"fork":false,"pushed_at":"2024-06-16T11:34:38.000Z","size":232,"stargazers_count":768,"open_issues_count":2,"forks_count":98,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-09T03:09:34.645Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/dotenv-safe","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/rolodato.png","metadata":{"files":{"readme":"README.markdown","changelog":"CHANGELOG.markdown","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}},"created_at":"2015-10-07T04:57:20.000Z","updated_at":"2025-04-04T13:27:23.000Z","dependencies_parsed_at":"2024-01-14T15:08:27.565Z","dependency_job_id":"d111b619-7ebb-4da8-8d51-ebf8fe45d5b6","html_url":"https://github.com/rolodato/dotenv-safe","commit_stats":{"total_commits":97,"total_committers":16,"mean_commits":6.0625,"dds":"0.48453608247422686","last_synced_commit":"1ab395c2045bc8a2737da1a683cb6d56605a08f4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolodato%2Fdotenv-safe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolodato%2Fdotenv-safe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolodato%2Fdotenv-safe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolodato%2Fdotenv-safe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rolodato","download_url":"https://codeload.github.com/rolodato/dotenv-safe/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254120179,"owners_count":22017953,"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":[],"created_at":"2024-07-31T16:01:16.899Z","updated_at":"2025-05-14T10:12:47.149Z","avatar_url":"https://github.com/rolodato.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","🔧 Utilities \u0026 Miscellaneous"],"sub_categories":[],"readme":"# dotenv-safe [![Build Status](https://github.com/rolodato/dotenv-safe/actions/workflows/node.js.yml/badge.svg)](https://github.com/rolodato/dotenv-safe/actions/workflows/node.js.yml)\n\nIdentical to [`dotenv`](https://github.com/motdotla/dotenv), but ensures that all needed environment variables are defined after reading from `.env`.\nThe names of the needed variables are read from `.env.example`, which should be commited along with your project.\n\n`dotenv-safe` only checks if all the needed variable names exist in `process.env` after initialising. It does not assume anything about the presence, format or validity of the values.\n\n# Installation\n\n```\nnpm install dotenv-safe\n```\n\n```\npnpm install dotenv-safe\n```\n\n```\nyarn add dotenv-safe\n```\n\n# Example\n\n```dosini\n# .env.example, committed to repo\nSECRET=\nTOKEN=\nKEY=\n```\n\n```dosini\n# .env, private\nSECRET=topsecret\nTOKEN=\n```\n\n```js\n// index.js\nrequire('dotenv-safe').config();\n```\n\nOr, if you are using [ES modules](https://nodejs.org/api/esm.html):\n\n```js\n// index.mjs\nimport { config } from 'dotenv-safe';\nconfig();\n```\n\nSince the provided `.env` file does not contain all the variables defined in\n`.env.example`, an exception is thrown:\n\n```\nMissingEnvVarsError: The following variables were defined in .env.example but are not present in the environment:\n  TOKEN, KEY\nMake sure to add them to .env or directly to the environment.\n\nIf you expect any of these variables to be empty, you can use the allowEmptyValues option:\nrequire('dotenv-safe').config({\n  allowEmptyValues: true\n});\n```\n\nNot all the variables have to be defined in `.env`; they can be supplied externally.\nFor example, the following would work:\n\n```\n$ TOKEN=abc KEY=xyz node index.js\n```\n\n# Usage\n\nRequiring and loading is identical:\n\n```js\nrequire('dotenv-safe').config();\n```\n\nThis will load environment variables from `.env` as usual, but will also read any variables defined in `.env.example`.\nIf any variables are already defined in the environment before reading from `.env`, they will not be overwritten.\nIf any variables are missing from the environment, a [`MissingEnvVarsError`](MissingEnvVarsError.js) will be thrown, which lists the missing variables.\nOtherwise, returns an object with the following format:\n\n```js\n{\n  parsed: { SECRET: 'topsecret', TOKEN: '' },          // parsed representation of .env\n  required: { SECRET: 'topsecret', TOKEN: 'external' } /* key-value pairs required by .env.example\n                                                          and defined by environment */\n}\n```\n\nIf all the required variables were successfully read but an error was thrown when trying to read the `.env` file, the error will be included in the result object under the `error` key.\n\n`dotenv-safe` compares the actual environment after loading `.env` (if any) with the example file, so it will work correctly if environment variables are missing in `.env` but provided through other means such as a shell script.\n\n## Preloading\n\nYou can use the `--require` (`-r`) command line option to preload dotenv-safe.\nBy doing this, you do not need to require and load dotenv in your application code.\nThis is the preferred approach when using import instead of require.\n\n```\n$ node -r dotenv-safe/config your_script.js\n```\n\n[See the dotenv README for more information](https://github.com/motdotla/dotenv#preload).\n\n## Continuous integration (CI)\n\nIt can be useful to depend on a different set of example variables when running in a CI environment.\nThis can be done by checking if the `CI` environment variable is defined, which is supported by virtually all CI solutions.\nFor example:\n\n```js\nrequire('dotenv-safe').config({\n  example: process.env.CI ? '.env.ci.example' : '.env.example'\n});\n```\n\n# Options\n\n[Same options and methods supported by `dotenv`](https://github.com/motdotla/dotenv#options), in addition to the options below:\n\n```js\nrequire('dotenv-safe').config({\n    allowEmptyValues: true,\n    example: './.my-env-example-filename'\n});\n```\n\nStarting from version 9.0.0, `dotenv` is a peer dependency of `dotenv-safe`. This means that the actual version of `dotenv` used defaults to the latest available at install time, or whatever is specified by your application.\n\n## `allowEmptyValues`\n\nIf a variable is defined in the example file and has an empty value in the environment, enabling this option will not throw an error after loading.\nDefaults to `false`.\n\n## `example`\n\nPath to example environment file.\nDefaults to `.env.example`.\n\n# Motivation\n\nI regularly use apps that depend on `.env` files but don't validate if all the necessary variables have been defined correctly.\nInstead of having to document and validate this manually, I prefer to commit a self-documenting `.env.example` file that may have placeholder or example values filled in. This can be used as a template or starting point for an actual `.env` file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frolodato%2Fdotenv-safe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frolodato%2Fdotenv-safe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frolodato%2Fdotenv-safe/lists"}