{"_id":"@dabharat/env-guard","_rev":"2-8aef1033379b3562ea574956ed3026e6","name":"@dabharat/env-guard","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@dabharat/env-guard","version":"1.0.0","keywords":["env","validation","cli","dotenv"],"author":{"name":"DAbharat"},"license":"ISC","_id":"@dabharat/env-guard@1.0.0","maintainers":[{"name":"dabharat","email":"bhardemo27@gmail.com"}],"homepage":"https://github.com/DAbharat/env-guard#readme","bugs":{"url":"https://github.com/DAbharat/env-guard/issues"},"bin":{"env-guard":"src/cli/index.js"},"dist":{"shasum":"4ae3589c6e41e521d8aa5526bc2cbe73cd0875a7","tarball":"https://registry.npmjs.org/@dabharat/env-guard/-/env-guard-1.0.0.tgz","fileCount":8,"integrity":"sha512-QAVSD2xzLao/dfc04M0xhul4NPcWqSBu8rV5ztSXp09voSuUY+V9G7qkCn6w77NSUhQ/7qs0eaB6CbIN4H/eiw==","signatures":[{"sig":"MEUCIQDnBY5GY/A+KeNyUYbrUm7LBQu6JOuItysjbMu7kb4ZHgIgT6YGwBvrelwdr5rCgA3XZBm5XhOCLyuQYv/A4h2UivA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25790},"main":"index.js","type":"module","engines":{"npm":">=8.0.0","node":">=16.0.0"},"gitHead":"971ddebcc8eafac4990f3bb8b8d3d31ab249ddcb","scripts":{"lint":"eslint src/","test":"node --experimental-vm-modules node_modules/jest/bin/jest.js","lint:fix":"eslint src/ --fix","test:watch":"node --experimental-vm-modules node_modules/jest/bin/jest.js --watch","test:coverage":"node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"},"_npmUser":{"name":"dabharat","email":"bhardemo27@gmail.com"},"repository":{"url":"git+https://github.com/DAbharat/env-guard.git","type":"git"},"_npmVersion":"10.9.2","description":"Environment variable validation tool for Node.js applications","directories":{},"_nodeVersion":"22.16.0","dependencies":{"dotenv":"^17.4.1"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.3.0","eslint":"^10.2.0","@eslint/js":"^10.0.1"},"_npmOperationalInternal":{"tmp":"tmp/env-guard_1.0.0_1775746788324_0.31763979236886963","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"bin":{"env-guard":"src/cli/index.js"},"name":"@dabharat/env-guard","version":"1.0.2","description":"Environment variable validation tool for Node.js applications","author":{"name":"DAbharat"},"main":"index.js","type":"module","engines":{"node":">=16.0.0","npm":">=8.0.0"},"repository":{"type":"git","url":"git+https://github.com/DAbharat/env-guard.git"},"scripts":{"lint":"eslint src/","lint:fix":"eslint src/ --fix","test":"node --experimental-vm-modules node_modules/jest/bin/jest.js","test:watch":"node --experimental-vm-modules node_modules/jest/bin/jest.js --watch","test:coverage":"node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"},"keywords":["env","validation","cli","dotenv"],"license":"ISC","dependencies":{"dotenv":"^17.4.1"},"devDependencies":{"@eslint/js":"^10.0.1","eslint":"^10.2.0","jest":"^30.3.0"},"_id":"@dabharat/env-guard@1.0.2","gitHead":"296ef81a78d82be37fb52351aecbdb4986761d1d","bugs":{"url":"https://github.com/DAbharat/env-guard/issues"},"homepage":"https://github.com/DAbharat/env-guard#readme","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-fijs+X0xiQ7kSFWqpS+RgGfBggqZ4ab0wQcghNzKN+wFaixFQtLkAFqAxaGvJ7I7qIPeiqK62LVY9DyVvHCWqA==","shasum":"dbacc171024ead836cab4e1b7a6214250dddad4e","tarball":"https://registry.npmjs.org/@dabharat/env-guard/-/env-guard-1.0.2.tgz","fileCount":9,"unpackedSize":26260,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHZ2g1igBcP99urk/AH93rFm7scxRnUVCOjH+jhnXTP3AiEArkC9cq513DYXgVXfNrkd21vonbiw4TMsu/z2eQZyyQg="}]},"_npmUser":{"name":"dabharat","email":"bhardemo27@gmail.com"},"directories":{},"maintainers":[{"name":"dabharat","email":"bhardemo27@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/env-guard_1.0.2_1775834251955_0.9160985087724585"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-09T14:59:48.201Z","modified":"2026-04-10T15:17:32.226Z","1.0.0":"2026-04-09T14:59:48.461Z","1.0.2":"2026-04-10T15:17:32.101Z"},"bugs":{"url":"https://github.com/DAbharat/env-guard/issues"},"author":{"name":"DAbharat"},"license":"ISC","homepage":"https://github.com/DAbharat/env-guard#readme","keywords":["env","validation","cli","dotenv"],"repository":{"type":"git","url":"git+https://github.com/DAbharat/env-guard.git"},"description":"Environment variable validation tool for Node.js applications","maintainers":[{"name":"dabharat","email":"bhardemo27@gmail.com"}],"readme":"# env-guard\r\n\r\n[![npm version](https://img.shields.io/npm/v/%40dabharat%2Fenv-guard.svg)](https://www.npmjs.com/package/@dabharat/env-guard)\r\n[![License: ISC](https://img.shields.io/badge/License-ISC-yellow.svg)](https://opensource.org/licenses/ISC)\r\n[![Node.js Version](https://img.shields.io/node/v/%40dabharat%2Fenv-guard.svg)](https://nodejs.org/)\r\n\r\nA lightweight, production-ready environment variable validation tool for Node.js applications. Validate environment variables against a schema before your application starts, generate `.env.example` templates, and ensure type safety.\r\n\r\n## Features\r\n\r\n- ✅ **Schema-based validation** - Define required variables and their types\r\n- ✅ **Type checking** - Validates string, number, and boolean types\r\n- ✅ **Generate templates** - Auto-generate `.env.example` from schema\r\n- ✅ **Multiple .env file support** - Supports `.env`, `.env.local`, `.env.development`, `.env.production`\r\n- ✅ **CLI tool** - Built-in command-line interface with 7+ commands\r\n- ✅ **Minimal dependencies** - Only depends on `dotenv`\r\n- ✅ **Production ready** - Proper error handling and exit codes\r\n- ✅ **Fully tested** - Jest test suite with 30+ tests and 100% ESLint passing\r\n\r\n## Installation\r\n\r\n### From npm\r\n\r\n```bash\r\nnpm install @dabharat/env-guard\r\n```\r\n\r\nOr as a dev dependency:\r\n\r\n```bash\r\nnpm install --save-dev @dabharat/env-guard\r\n```\r\n\r\n### Run CLI\r\n\r\nVia npx:\r\n```bash\r\nnpx @dabharat/env-guard --help\r\n```\r\n\r\nOr if installed globally:\r\n```bash\r\nenv-guard --help\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Create a schema file (`env.schema.js`)\r\n\r\n```javascript\r\nexport default {\r\n    DATABASE_URL: { \r\n        type: \"string\", \r\n        required: true \r\n    },\r\n    API_PORT: { \r\n        type: \"number\", \r\n        required: true \r\n    },\r\n    DEBUG: { \r\n        type: \"boolean\", \r\n        required: false \r\n    }\r\n};\r\n```\r\n\r\n### 2. Generate `.env.example` template\r\n\r\n```bash\r\nenv-guard --generate\r\n```\r\n\r\nThis creates `.env.example` based on your schema:\r\n\r\n```env\r\n# DATABASE_URL (required)\r\nDATABASE_URL=your_value_here\r\n\r\n# API_PORT (required)\r\nAPI_PORT=3000\r\n\r\n# DEBUG (optional)\r\nDEBUG=true\r\n```\r\n\r\n### 3. Copy and fill in the template\r\n\r\n```bash\r\ncp .env.example .env\r\n# Edit .env with your actual values\r\nnano .env\r\n```\r\n\r\n### 4. Validate on startup\r\n\r\n```bash\r\nenv-guard\r\n```\r\n\r\n**Output:**\r\n```\r\n[env-guard]: Loaded 3 variables. Summary: 3 passed, 0 missing, 0 invalid.\r\n```\r\n\r\n## CLI Commands\r\n\r\n```bash\r\n# Validate environment variables\r\nenv-guard\r\n\r\n# Generate .env.example from schema (NEW!)\r\nenv-guard --generate\r\n# or\r\nenv-guard -g\r\n\r\n# Show help\r\nenv-guard --help\r\n# or\r\nenv-guard -h\r\n\r\n# Show version\r\nenv-guard --version\r\n# or\r\nenv-guard -v\r\n\r\n# Enable debug logging\r\nenv-guard --debug\r\n# or\r\nenv-guard -d\r\n\r\n# Minimal output (errors only)\r\nenv-guard --quiet\r\n# or\r\nenv-guard -q\r\n\r\n# Specify custom schema file\r\nenv-guard --schema ./config/schema.js\r\n\r\n# Override existing environment variables from .env\r\nenv-guard --override\r\n# or\r\nenv-guard -o\r\n```\r\n\r\n## Schema Definition\r\n\r\nEach variable in the schema object should define:\r\n\r\n- `type` (optional) - Data type: `\"string\"`, `\"number\"`, or `\"boolean\"`\r\n- `required` (optional, default: false) - Whether the variable must be present\r\n\r\n```javascript\r\nexport default {\r\n    // Required string variable\r\n    DATABASE_URL: { \r\n        type: \"string\", \r\n        required: true \r\n    },\r\n\r\n    // Required number variable\r\n    API_PORT: { \r\n        type: \"number\", \r\n        required: true \r\n    },\r\n\r\n    // Optional boolean variable\r\n    DEBUG: { \r\n        type: \"boolean\", \r\n        required: false \r\n    },\r\n\r\n    // Required variable (any type)\r\n    APP_NAME: { \r\n        required: true \r\n    }\r\n};\r\n```\r\n\r\n## Environment File Fallback\r\n\r\nenv-guard checks for environment files in this order:\r\n\r\n1. `.env` (or custom file specified with `--schema`)\r\n2. `.env.local` (for local overrides, typically gitignored)\r\n3. `.env.development` (for development-specific variables)\r\n4. `.env.production` (for production-specific variables)\r\n\r\nThe first file found will be used. If none exist, validation fails with an error.\r\n\r\n## Type Validation\r\n\r\n### String Type\r\n```javascript\r\nDATABASE_URL: { type: \"string\", required: true }\r\n```\r\nValidates that the value is a string. Empty strings are rejected for required variables.\r\n\r\n### Number Type\r\n```javascript\r\nAPI_PORT: { type: \"number\", required: true }\r\n```\r\nValidates that the value can be converted to a number. Strings like `\"3000\"` are accepted.\r\n\r\n### Boolean Type\r\n```javascript\r\nDEBUG: { type: \"boolean\", required: true }\r\n```\r\nAccepts: `true`, `false`, `\"true\"`, `\"false\"`, `\"TRUE\"`, `\"FALSE\"` (case-insensitive)\r\n\r\n## Validation Output\r\n\r\n### Success\r\n```\r\n[env-guard]: Loaded 3 variables. Summary: 3 passed, 0 missing, 0 invalid.\r\n```\r\n\r\n### Missing variables\r\n```\r\n[env-guard]: Missing environment variables: SECRET_KEY, API_TOKEN\r\n  - SECRET_KEY is missing\r\n  - API_TOKEN is missing\r\n```\r\n\r\n### Invalid types\r\n```\r\n[env-guard]: Invalid environment variables:\r\n  - PORT is invalid. Expected type: number, Received value: abc (type: string). \r\n    Reason: Expected number, received value that cannot be converted to a number\r\n```\r\n\r\n## Exit Codes\r\n\r\n- `0` - Validation successful or generation successful\r\n- `1` - Validation failed (missing/invalid variables) or generation failed\r\n\r\n## Integration with npm Scripts\r\n\r\nAdd env-guard to your npm scripts to validate before starting your application:\r\n\r\n```json\r\n{\r\n  \"scripts\": {\r\n    \"start\": \"env-guard && node src/index.js\",\r\n    \"dev\": \"env-guard --debug && node --watch src/index.js\",\r\n    \"validate\": \"env-guard\",\r\n    \"setup\": \"env-guard --generate && cp .env.example .env\"\r\n  }\r\n}\r\n```\r\n\r\nThen run:\r\n```bash\r\nnpm start              # Start with validation\r\nnpm run dev           # Development with debug logs\r\nnpm run setup         # Generate and copy .env template\r\nnpm run validate      # Just validate (no start)\r\n```\r\n\r\nThe application will only start if all environment variables pass validation.\r\n\r\n## Testing\r\n\r\nThe package includes comprehensive tests covering all features.\r\n\r\nRun the full test suite:\r\n\r\n```bash\r\nnpm test\r\n```\r\n\r\nRun tests in watch mode (auto-rerun on changes):\r\n\r\n```bash\r\nnpm test:watch\r\n```\r\n\r\nGenerate coverage report:\r\n\r\n```bash\r\nnpm test:coverage\r\n```\r\n\r\n### Test Coverage\r\n\r\nThe project includes **30+ tests** covering:\r\n- ✅ String, number, and boolean type validation\r\n- ✅ Required and optional variables\r\n- ✅ Missing variable detection\r\n- ✅ Invalid type handling\r\n- ✅ Environment file loading and fallbacks\r\n- ✅ Template generation from schema\r\n- ✅ File overwrite protection\r\n- ✅ Edge cases and error conditions\r\n\r\nAll tests pass with 100% success rate.\r\n\r\n## Development\r\n\r\n### Setup\r\n\r\nClone the repository and install dependencies:\r\n\r\n```bash\r\ngit clone https://github.com/DAbharat/env-guard.git\r\ncd env-guard\r\nnpm install\r\n```\r\n\r\n### Linting\r\n\r\nCheck code quality:\r\n\r\n```bash\r\nnpm run lint\r\n```\r\n\r\nAuto-fix linting issues:\r\n\r\n```bash\r\nnpm run lint:fix\r\n```\r\n\r\n### Running the CLI Locally\r\n\r\n```bash\r\nnode src/cli/index.js\r\n```\r\n\r\n## Example: Real-World Setup\r\n\r\n### Project: Node.js API Server\r\n\r\n**env.schema.js**\r\n```javascript\r\nexport default {\r\n    DATABASE_URL: { type: \"string\", required: true },\r\n    DATABASE_PASSWORD: { type: \"string\", required: true },\r\n    API_PORT: { type: \"number\", required: true },\r\n    API_HOST: { type: \"string\", required: false },\r\n    NODE_ENV: { type: \"string\", required: true },\r\n    LOG_LEVEL: { type: \"string\", required: false },\r\n    JWT_SECRET: { type: \"string\", required: true }\r\n};\r\n```\r\n\r\n**package.json**\r\n```json\r\n{\r\n  \"name\": \"my-api\",\r\n  \"scripts\": {\r\n    \"setup\": \"env-guard --generate && echo 'Now edit .env with your values'\",\r\n    \"validate\": \"env-guard\",\r\n    \"start\": \"env-guard && node src/server.js\",\r\n    \"dev\": \"env-guard --debug && node --watch src/server.js\"\r\n  },\r\n  \"dependencies\": {\r\n    \"@dabharat/env-guard\": \"^1.0.0\"\r\n  }\r\n}\r\n```\r\n\r\n**Workflow**\r\n\r\n```bash\r\n# 1. First time setup\r\nnpm run setup\r\n\r\n# 2. Edit .env with actual values\r\nnano .env\r\n\r\n# 3. Start server (validates first)\r\nnpm start\r\n\r\n# 4. Development (with debug logs)\r\nnpm run dev\r\n```\r\n\r\n## Error Messages\r\n\r\nAll error messages are prefixed with `[env-guard]:` for easy identification in logs.\r\n\r\nCommon errors:\r\n\r\n```\r\n[env-guard]: Error - .env file not found in project root\r\n\r\n[env-guard]: Error - env.schema.js file not found at: /path/to/env.schema.js\r\n\r\n[env-guard]: Missing environment variables: DATABASE_URL\r\n\r\n[env-guard]: Invalid environment variables: API_PORT\r\n\r\n[env-guard]: Warning: .env.example already exists. Skipping generation to avoid overwriting.\r\n```\r\n\r\n## Version History\r\n\r\n### v1.0.0 (Latest)\r\n- ✨ Initial release\r\n- ✨ Schema-based validation\r\n- ✨ CLI with 7 commands\r\n- ✨ Generate .env.example templates\r\n- ✨ Type checking (string, number, boolean)\r\n- ✨ Multiple .env file support\r\n- ✨ 30+ tests with full coverage\r\n\r\n## Requirements\r\n\r\n- **Node.js**: >= 16.0.0\r\n- **npm**: >= 8.0.0\r\n\r\n## License\r\n\r\nISC\r\n\r\n## Support & Contributing\r\n\r\nFor issues, feature requests, or questions:\r\n- **GitHub**: https://github.com/DAbharat/env-guard\r\n- **npm Package**: https://www.npmjs.com/package/@dabharat/env-guard\r\n- **Issues**: https://github.com/DAbharat/env-guard/issues\r\n\r\n## Author\r\n\r\n**DAbharat** - [@DAbharat](https://github.com/DAbharat)\r\n\r\n---\r\n\r\n**Made with ❤️ for the Node.js community**\r\n\r\n","readmeFilename":"README.md"}