{"id":21343970,"url":"https://github.com/efstajas/validate-env","last_synced_at":"2025-08-02T13:42:35.218Z","repository":{"id":57110784,"uuid":"260925619","full_name":"efstajas/validate-env","owner":"efstajas","description":"🚓📋⚠️ A simple node.js utility that type-checks your process.env variables based on a .env.template file.","archived":false,"fork":false,"pushed_at":"2023-12-21T16:08:48.000Z","size":27,"stargazers_count":17,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-25T16:03:06.121Z","etag":null,"topics":["environment-variables","nodejs","nodejs-modules","typescript","utility","validation","validator"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/efstajas.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}},"created_at":"2020-05-03T13:25:43.000Z","updated_at":"2023-12-21T16:08:52.000Z","dependencies_parsed_at":"2023-12-24T00:27:15.490Z","dependency_job_id":"ae925f08-8376-4733-8f4d-15b139671bc5","html_url":"https://github.com/efstajas/validate-env","commit_stats":{"total_commits":38,"total_committers":1,"mean_commits":38.0,"dds":0.0,"last_synced_commit":"cfe200835d643a259d1ae89f1771ee960b092188"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efstajas%2Fvalidate-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efstajas%2Fvalidate-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efstajas%2Fvalidate-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efstajas%2Fvalidate-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/efstajas","download_url":"https://codeload.github.com/efstajas/validate-env/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225824592,"owners_count":17529906,"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":["environment-variables","nodejs","nodejs-modules","typescript","utility","validation","validator"],"created_at":"2024-11-22T01:16:33.648Z","updated_at":"2024-11-22T01:16:34.250Z","avatar_url":"https://github.com/efstajas.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚓 validate-env\n\n![Node.js 10.x and 12.x CI](https://github.com/efstajas/validate-env/workflows/Node.js%2010.x%20and%2012.x%20CI/badge.svg)\n\nA small utility for checking process.env based on a .env.template file in node.js. You can use it to make sure all your env variables are set before running your application, and optionally ensure they're of the right types too.\n\n## ⬇️ Install\n\nSimply install with npm or yarn. validate-env is available on the NPM registry and on GitHub Packages.\n\n```\nnpm install @efstajas/validate-env\n\nor\n\nyarn add @efstajas/validate-env\n```\n\n## 🎬 Getting started\n\nFirst, create your `.env.template` file. This file contains all the .env variables you want to validate for. While you should never commit a .env file, committing the .env.template makes a lot of sense — everyone working on your project can see immediately what values they need, and validation will work as expected on any client. An example `.env.template` might look something like this:\n\n```\nFOO=string\nBAR=number\nFOOBAR=array\nFOOBARFOO=boolean?\n```\n\nThis `.env.template` means you expect all the variables FOO, BAR, and FOOBAR to exist. The `?` at the end of the FOOBARFOO variable's type means that it's an optional value — so, validation won't fail if it's not set, but if it is, it must be of type `boolean`. As you can see, after the =, you can specify a type for that given variable:\n\n- `number` means your variable must be numeric, meaning it can be something like `1` or `004` or even `6e+2`.\n- `array` means your variable must be a valid JSON array, like `[\"foo\", 123]`. Please note it must be **valid JSON**, meaning strings are to be double-quoted.\n- `boolean` means your variable must be either `'true'` or `'false'` \n- `string` means your variable must be a valid string. In practice, *any value will pass this test*, because .env variables are always strings.\n\n💡*You can put comments in your env template by using `#`. Great for annotations or sharing default values!*\n\n### Usage\n\nTo run the test, simply import the main function, and pass it your `.env.template` file path. It returns a Promise that will resolve to a `ValidatorResult`. \n\n```ts\nimport validateEnv from '@efstajas/validate-env'\n\nvalidateEnv('./path/to/your/.env.template').then((r) =\u003e {\n  if (r.result === 'pass') {\n    // Your .env is valid!\n  }\n\n  if (r.result === 'fail') {\n    // Something is wrong in your .env\n  }\n}).catch((e) =\u003e {\n  /*\n  Something went wrong while validating —\n  maybe we couldn't open the file, or the\n  template itself is invalid.\n  */\n  console.error(e)\n})\n```\n\nThe `ValidatorResult` contains either a `SuccessPayload` like `{ result: 'pass' }`, or a `FailedPayload` which includes more info about what exactly failed:\n\n```ts\nvalidateEnv('./path/to/your/.env.template').then((r) =\u003e {\n  if (r.result === 'fail') {\n    const { failedVar } = r\n\n    const {\n      name,\n      expectedType\n    } = failedVar\n\n    switch (failedVar.reason) {\n      case 'MISSING':\n        // Variable is missing from .env\n      case 'WRONG_TYPE':\n        // Variable is present, but doesn't match expected type\n    }\n  }\n})\n```\n\n### Normal usage: Validating .env before starting your app\n\nUsually, you would want to validate your `.env` at the very beginning of your app, and if it fails, don't even initialize it. The best way to achieve this is to just wrap your initialization routine into a function, and then call it only if the `validateEnv` result indicates that your `.env` is valid. For an express application, it could look something like this:\n\n```ts\n// Use dotenv to load .env file into process.env\nimport * as dotenv from 'dotenv'\ndotenv.config()\n\nimport express from 'express'\nimport validateEnv from '@efstajas/validate-env'\n\nconst initializeApplication = () =\u003e {\n  const server = express.server\n\n  // Register routes, middleware etc.\n\n  server.listen(8000)\n}\n\nvalidateEnv('./.env.template').then((r) =\u003e {\n  if (r.result === 'pass') {\n    initializeApplication()\n  }\n})\n```\n\n### Silent mode\n\nBy default, `validate-env` prints warnings or a success message to the console automatically after validation. If you want to handle logs by yourself, you can disable this behavior by passing the `silent` option:\n\n```ts\nvalidateEnv('./.env.template', { silent: true }).then((r) =\u003e {\n  if (r.result === 'fail') {\n    const { failedVar } = r\n\n    const {\n      name,\n      expectedType\n    } = failedVar\n\n    switch (failedVar.reason) {\n      case 'MISSING':\n        console.log(`Variable ${name} is missing in .env. Expected type: ${expectedType}`)\n        break\n      case 'WRONG_TYPE':\n        console.log(`Variable ${name} isn't of expected type ${expectedType}.`)\n        break\n    }\n\n    return\n  }\n\n  console.log('.env is valid 🎉')\n  initializeApplication()\n  }\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fefstajas%2Fvalidate-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fefstajas%2Fvalidate-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fefstajas%2Fvalidate-env/lists"}