{"id":30892404,"url":"https://github.com/hoangsonww/envguard-env-validator","last_synced_at":"2025-10-28T04:13:28.471Z","repository":{"id":282766859,"uuid":"949592462","full_name":"hoangsonww/EnvGuard-Env-Validator","owner":"hoangsonww","description":"🛡️ EnvGuard – A powerful NPM package that validates your .env files against a predefined schema, ensuring all required environment variables are set and secure. Prevent misconfigurations in production by detecting missing values, insecure defaults, and enforcing .env.example consistency across teams.","archived":false,"fork":false,"pushed_at":"2025-08-01T22:40:51.000Z","size":68,"stargazers_count":21,"open_issues_count":0,"forks_count":20,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-09-08T19:37:43.266Z","etag":null,"topics":["env-example","env-file","env-schema","env-vars","environment","environment-variables","javascript","jest","node","node-js","node-package","node-package-manager","nodejs","npm","npm-package","schema-validator","security","typescript","validation","validator"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@hoangsonw/env-guard","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/hoangsonww.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":"2025-03-16T19:41:13.000Z","updated_at":"2025-06-21T17:16:56.000Z","dependencies_parsed_at":"2025-03-16T20:35:50.897Z","dependency_job_id":"a22a344f-a000-4502-b744-06294f86d6b3","html_url":"https://github.com/hoangsonww/EnvGuard-Env-Validator","commit_stats":null,"previous_names":["hoangsonww/envguard-env-validator"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hoangsonww/EnvGuard-Env-Validator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FEnvGuard-Env-Validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FEnvGuard-Env-Validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FEnvGuard-Env-Validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FEnvGuard-Env-Validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hoangsonww","download_url":"https://codeload.github.com/hoangsonww/EnvGuard-Env-Validator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoangsonww%2FEnvGuard-Env-Validator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274231433,"owners_count":25245585,"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","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["env-example","env-file","env-schema","env-vars","environment","environment-variables","javascript","jest","node","node-js","node-package","node-package-manager","nodejs","npm","npm-package","schema-validator","security","typescript","validation","validator"],"created_at":"2025-09-08T19:45:30.164Z","updated_at":"2025-10-28T04:13:23.442Z","avatar_url":"https://github.com/hoangsonww.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ EnvGuard – Validate \u0026 Secure Your Environment Variables\n\n[![NPM version](https://img.shields.io/npm/v/env-guard.svg?style=flat\u0026logo=npm)](https://www.npmjs.com/package/env-guard) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat\u0026logo=opensource)](LICENSE) [![Node.js](https://img.shields.io/badge/Node-%3E%3D14-brightgreen.svg?style=flat\u0026logo=node.js)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue.svg?style=flat\u0026logo=typescript)](https://www.typescriptlang.org/) [![Jest](https://img.shields.io/badge/Jest-27.0%2B-cyan.svg?style=flat\u0026logo=jest)](https://jestjs.io/)\n\n**EnvGuard** is an NPM package that validates your environment variables against a defined schema and enforces consistency with your `.env.example` file. Protect your application from misconfigurations and insecure defaults when working in teams or deploying to production.\n\nCurrently available on NPM: [https://www.npmjs.com/package/@hoangsonw/env-guard](https://www.npmjs.com/package/@hoangsonw/env-guard)\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Basic Usage](#basic-usage)\n  - [Advanced Usage](#advanced-usage)\n- [API Reference](#api-reference)\n- [Testing](#testing)\n- [Building \u0026 Publishing](#building--publishing)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Features\n\n- **Schema Validation:** Define required environment variables and insecure default values.\n- **.env Enforcement:** Compare your actual `.env` file against a provided `.env.example` file.\n- **Configurable Behavior:** Choose whether to warn or throw errors, and control key matching.\n- **TypeScript Support:** Fully written in TypeScript with complete type definitions.\n- **Cross-Platform:** Works in Node.js and integrates seamlessly into your deployment workflows.\n\n---\n\n## Installation\n\n### Prerequisites\n\n- Node.js v14 or higher\n- npm v6 or higher\n\n### Installing via NPM\n\n```bash\nnpm install @hoangsonw/env-guard\n```\n\n### Installing via Yarn\n\n```bash\nyarn add @hoangsonw/env-guard\n```\n\n---\n\n## Usage\n\nEnvGuard validates your environment variables based on a schema. It loads variables from your `.env` file and compares them against a reference `.env.example`.\n\n### Basic Usage\n\nCreate a schema for your environment variables and validate:\n\n```ts\nimport { validateEnv } from \"@hoangsonw/env-guard\";\n\nconst schema = {\n  DB_HOST: { required: true, insecureValues: [\"localhost\", \"127.0.0.1\"] },\n  DB_PASSWORD: { required: true, insecureValues: [\"12345\", \"password\"] },\n  DB_USER: { required: false },\n};\n\nvalidateEnv({\n  schema,\n  envFilePath: \"./.env\", // Defaults to \"./.env\"\n  exampleFilePath: \"./.env.example\", // Defaults to \"./.env.example\"\n  allowMissingExampleKeys: false, // Warn if keys mismatch\n  throwOnError: false, // Only warn; set to true to throw errors\n});\n```\n\n### Advanced Usage\n\nYou can customize EnvGuard’s behavior by changing options:\n\n- **`allowMissingExampleKeys`**: When `false`, it warns if there are extra keys in your `.env` or missing keys compared to `.env.example`.\n- **`throwOnError`**: When `true`, the function will throw errors instead of just logging warnings.\n\nExample:\n\n```ts\nimport { validateEnv } from \"@hoangsonw/env-guard\";\n\nconst schema = {\n  API_KEY: { required: true },\n  DB_HOST: { required: true, insecureValues: [\"localhost\"] },\n  DB_PASSWORD: { required: true, insecureValues: [\"password\", \"12345\"] },\n};\n\ntry {\n  validateEnv({\n    schema,\n    envFilePath: \"./config/.env\",\n    exampleFilePath: \"./config/.env.example\",\n    allowMissingExampleKeys: false,\n    throwOnError: true,\n  });\n  console.log(\"Environment variables validation passed!\");\n} catch (error) {\n  console.error(\"Environment validation failed:\", error);\n  process.exit(1);\n}\n```\n\n\u003e Note: The script might also parse environment variables from outside the `.env` file if they are already set in the environment of your machine or Node.js process. This can lead to some warnings in the console, if they are not defined in the `.env.example` file. You can safely ignore them.\n\n---\n\n## API Reference\n\n### `validateEnv(options: EnvGuardOptions): void`\n\n**Parameters:**\n\n- **`schema: EnvSchema`**  \n  An object defining each environment variable’s requirements.  \n  _Example:_\n\n  ```ts\n  {\n    DB_HOST: { required: true, insecureValues: [\"localhost\"] },\n    API_KEY: { required: true }\n  }\n  ```\n\n- **`envFilePath?: string`**  \n  Path to your `.env` file. Defaults to `\"./.env\"`.\n\n- **`exampleFilePath?: string`**  \n  Path to your `.env.example` file. Defaults to `\"./.env.example\"`.\n\n- **`allowMissingExampleKeys?: boolean`**  \n  If set to `false`, EnvGuard will warn about extra keys or missing keys between `.env` and `.env.example`.\n\n- **`throwOnError?: boolean`**  \n  If `true`, the function will throw an error when validations fail; otherwise, it will only log warnings.\n\n**Returns:**  \nNothing; it performs validation and logs warnings/errors as configured.\n\n---\n\n## Testing\n\nEnvGuard includes a Jest test suite. To run tests:\n\n1. **Install dependencies:**\n\n   ```bash\n   npm install\n   ```\n\n2. **Run tests:**\n   ```bash\n   npm test\n   ```\n\nTest files in the `__tests__` directory demonstrate how EnvGuard validates environment variables and compares `.env` to `.env.example`.\n\n---\n\n## Demo Scripts\n\nRun the demo scripts in the `__tests__` directory to see EnvGuard in action:\n\n1. **Run the demo script (with no `basedir` option):**\n   ```bash\n   npm run demoNoBasedir\n   ```\n2. **Run the demo script (with `basedir` option):**\n   ```bash\n    npm run demoWithBasedir\n   ```\n\nThe demo scripts will show how EnvGuard validates environment variables and compares `.env` to `.env.example`. Check the console output for validation results.\n\n---\n\n## Building \u0026 Publishing\n\n### Building\n\nCompile the TypeScript source:\n\n```bash\nnpm run build\n```\n\n### Publishing\n\n1. **Login to npm:**\n   ```bash\n   npm login\n   ```\n2. **Publish the package:**\n   ```bash\n   npm publish --access public\n   ```\n\n---\n\n## Contributing\n\nContributions are welcome! Follow these steps:\n\n1. **Fork the Repository**\n2. **Create a Feature Branch:**\n   ```bash\n   git checkout -b feature/my-new-feature\n   ```\n3. **Commit Your Changes**\n4. **Submit a Pull Request**\n\nFor major changes, please open an issue first to discuss your ideas. If you have any questions or need help, feel free to reach out.\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n## Final Remarks\n\nEnvGuard ensures your environment variables are correctly configured and secure, reducing misconfigurations in team settings and production deployments. With schema validation and `.env.example` enforcement, it helps maintain consistency and security in your projects.\n\nHappy guarding! 🛡️\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoangsonww%2Fenvguard-env-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhoangsonww%2Fenvguard-env-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoangsonww%2Fenvguard-env-validator/lists"}