{"id":41879134,"url":"https://github.com/princeofv/envguards","last_synced_at":"2026-01-26T18:01:14.710Z","repository":{"id":333061148,"uuid":"1136090291","full_name":"princeofv/envguards","owner":"princeofv","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-17T03:47:17.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T15:34:39.224Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/princeofv.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-17T03:40:31.000Z","updated_at":"2026-01-17T03:47:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/princeofv/envguards","commit_stats":null,"previous_names":["princeofv/envguards"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/princeofv/envguards","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeofv%2Fenvguards","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeofv%2Fenvguards/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeofv%2Fenvguards/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeofv%2Fenvguards/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/princeofv","download_url":"https://codeload.github.com/princeofv/envguards/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeofv%2Fenvguards/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28784093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"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":[],"created_at":"2026-01-25T13:00:20.520Z","updated_at":"2026-01-26T18:01:14.703Z","avatar_url":"https://github.com/princeofv.png","language":"TypeScript","readme":"# envguards\n\n\u003e 🛡️ Framework-agnostic environment variable validation, documentation generator, and `.env.example` creator.\n\n[![npm version](https://img.shields.io/npm/v/envguards.svg)](https://www.npmjs.com/package/envguards)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Why envguards?\n\nManaging environment variables across different frameworks and environments is painful:\n\n- ❌ **Silent failures** - Missing env vars cause cryptic runtime errors\n- ❌ **No documentation** - Team members don't know what variables are needed\n- ❌ **Copy-paste errors** - Setting up new environments is error-prone\n- ❌ **Framework lock-in** - Most validation tools are framework-specific\n\n\n**envguards** solves all of this with a single, framework-agnostic solution:\n\n- ✅ **Fail fast** - Clear error messages at startup\n- ✅ **Auto-documentation** - Generate Markdown docs from your schema\n- ✅ **Auto `.env.example`** - Keep your example file in sync\n- ✅ **Works everywhere** - Node, Express, React, Next.js, Vite, Angular, Svelte, Bun, Deno\n\n## Installation\n\n```bash\nnpm install envguards\n```\n\n```bash\nyarn add envguards\n```\n\n```bash\npnpm add envguards\n```\n\n## Quick Start\n\n### 1. Define your schema\n\n\nCreate an `env.schema.js` (or `env.schema.ts`) file:\n\n```typescript\n// env.schema.ts\nexport const envSchema = {\n  DATABASE_URL: {\n    required: true,\n    description: \"PostgreSQL connection string\",\n    example: \"postgres://user:pass@localhost:5432/db\",\n  },\n\n  JWT_SECRET: {\n    required: true,\n    description: \"JWT signing secret for authentication\",\n  },\n\n  NODE_ENV: {\n    required: false,\n    default: \"development\",\n    description: \"Application environment\",\n    allowed: [\"development\", \"production\", \"test\"],\n  },\n\n  PORT: {\n    required: false,\n    default: \"3000\",\n    description: \"Server port number\",\n    example: \"8080\",\n  },\n\n  LOG_LEVEL: {\n    required: false,\n    default: \"info\",\n    description: \"Logging verbosity level\",\n    allowed: [\"debug\", \"info\", \"warn\", \"error\"],\n  },\n};\n```\n\n### 2. Validate at runtime\n\n```typescript\nimport { validateEnv } from \"envguards\";\nimport { envSchema } from \"./env.schema.js\";\n\n// Validates and throws if invalid\nvalidateEnv(envSchema);\n\n// Your app starts only if all env vars are valid!\nconsole.log(\"✅ Environment validated, starting server...\");\n```\n\n### 3. Generate documentation\n\n\n```bash\nnpx envguards generate\n```\n\n\nThis creates:\n- `ENVIRONMENT.md` - Markdown documentation\n- `.env.example` - Example environment file\n\n## Schema Definition\n\nEach environment variable can have these properties:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `required` | `boolean` | If `true`, validation fails when variable is missing |\n| `description` | `string` | Human-readable description (used in docs) |\n| `example` | `string` | Example value (used in docs and `.env.example`) |\n| `default` | `string` | Default value if not provided |\n| `allowed` | `string[]` | List of allowed values (enum validation) |\n\n```typescript\nimport { defineEnvSchema } from \"envguards\";\n\nexport const envSchema = defineEnvSchema({\n  // Required with description and example\n  API_KEY: {\n    required: true,\n    description: \"API key for external service\",\n    example: \"sk_live_xxxxx\",\n  },\n\n  // Optional with default\n  CACHE_TTL: {\n    required: false,\n    default: \"3600\",\n    description: \"Cache time-to-live in seconds\",\n  },\n\n  // Enum validation\n  LOG_FORMAT: {\n    required: false,\n    default: \"json\",\n    allowed: [\"json\", \"pretty\", \"compact\"],\n    description: \"Log output format\",\n  },\n});\n```\n\n## CLI Commands\n\n### `envguards generate`\n\nGenerates documentation and example files from your schema.\n\n\n```bash\nnpx envguards generate\n```\n\n**Options:**\n- `--schema \u003cpath\u003e` - Path to schema file (auto-detected by default)\n- `--cwd \u003cpath\u003e` - Working directory\n- `--md-file \u003cname\u003e` - Output markdown file name (default: `ENVIRONMENT.md`)\n- `--env-file \u003cname\u003e` - Output env file name (default: `.env.example`)\n- `--no-comments` - Don't include comments in `.env.example`\n- `--group` - Group variables by required/optional\n\n### `envguards check`\n\nValidates current environment against the schema. Exits with code `1` on error (CI-friendly).\n\n\n```bash\nnpx envguards check\n```\n\n**Options:**\n- `--schema \u003cpath\u003e` - Path to schema file\n- `--cwd \u003cpath\u003e` - Working directory\n\n## Generated Output\n\n### ENVIRONMENT.md\n\n\n```markdown\n# Environment Variables\n\nThis document describes all environment variables used by this application.\n\n| Name | Required | Default | Description | Example |\n|------|----------|---------|-------------|---------|\n| `DATABASE_URL` | ✅ | `—` | PostgreSQL connection string | postgres://... |\n| `JWT_SECRET` | ✅ | `—` | JWT signing secret | — |\n| `NODE_ENV` | ❌ | `development` | Application environment | development |\n| `PORT` | ❌ | `3000` | Server port number | 8080 |\n\n## Allowed Values\n\n### `NODE_ENV`\n\n- `development`\n- `production`\n- `test`\n```\n\n### .env.example\n\n\n```bash\n# Environment Variables\n# Generated by envguards\n\n# PostgreSQL connection string\n# [REQUIRED]\nDATABASE_URL=\n\n# JWT signing secret for authentication\n# [REQUIRED]\nJWT_SECRET=\n\n# Application environment\n# Allowed values: development, production, test\nNODE_ENV=development\n\n# Server port number\nPORT=3000\n```\n\n## Framework Examples\n\n### Node.js / Express\n\n```typescript\n// src/index.ts\nimport express from \"express\";\nimport { validateEnv } from \"envguards\";\nimport { envSchema } from \"./env.schema.js\";\n\n// Validate before anything else\nvalidateEnv(envSchema);\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\n\napp.listen(PORT, () =\u003e {\n  console.log(`Server running on port ${PORT}`);\n});\n```\n\n### React / Vite\n\n```typescript\n// src/env.ts\nimport { validateEnv } from \"envguards\";\n\nconst envSchema = {\n  VITE_API_URL: {\n    required: true,\n    description: \"Backend API URL\",\n    example: \"https://api.example.com\",\n  },\n  VITE_APP_TITLE: {\n    required: false,\n    default: \"My App\",\n    description: \"Application title\",\n  },\n};\n\n// Validate on app load\nvalidateEnv(envSchema, { env: import.meta.env });\n\nexport const config = {\n  apiUrl: import.meta.env.VITE_API_URL,\n  appTitle: import.meta.env.VITE_APP_TITLE,\n};\n```\n\n### Next.js\n\n```typescript\n// lib/env.ts\nimport { validateEnv } from \"envguards\";\n\nconst envSchema = {\n  DATABASE_URL: {\n    required: true,\n    description: \"Database connection string\",\n  },\n  NEXTAUTH_SECRET: {\n    required: true,\n    description: \"NextAuth.js secret\",\n  },\n  NEXTAUTH_URL: {\n    required: false,\n    default: \"http://localhost:3000\",\n    description: \"NextAuth.js URL\",\n  },\n};\n\n// Validate server-side environment\nvalidateEnv(envSchema);\n\n// For client-side (NEXT_PUBLIC_ vars)\nconst clientEnvSchema = {\n  NEXT_PUBLIC_API_URL: {\n    required: true,\n    description: \"Public API URL\",\n  },\n};\n\n// Validate in a client component or layout\nif (typeof window !== \"undefined\") {\n  validateEnv(clientEnvSchema);\n}\n```\n\n### Angular\n\n```typescript\n// src/environments/env.validator.ts\nimport { validateEnv } from \"envguards\";\n\nconst envSchema = {\n  NG_APP_API_URL: {\n    required: true,\n    description: \"Backend API URL\",\n  },\n  NG_APP_ENV: {\n    required: false,\n    default: \"development\",\n    allowed: [\"development\", \"production\"],\n  },\n};\n\n// Call during app initialization\nexport function validateEnvironment(): void {\n  validateEnv(envSchema);\n}\n```\n\n### Bun / Deno\n\n```typescript\n// env.ts\nimport { validateEnv } from \"envguards\";\n\nconst envSchema = {\n  PORT: {\n    required: false,\n    default: \"3000\",\n  },\n  DATABASE_URL: {\n    required: true,\n    description: \"Database connection string\",\n  },\n};\n\nvalidateEnv(envSchema);\n\n// Works with both Bun and Deno (Node-compat mode)\n```\n\n## API Reference\n\n### `validateEnv(schema, options?)`\n\nValidates environment variables against a schema.\n\n```typescript\nimport { validateEnv } from \"envguards\";\n\nconst result = validateEnv(schema, {\n  env: process.env,      // Custom env object (default: process.env)\n  throwOnError: true,    // Throw on validation error (default: true)\n});\n```\n\n**Returns:** `ValidationResult`\n```typescript\ninterface ValidationResult {\n  valid: boolean;\n  errors: ValidationError[];\n  values: Record\u003cstring, string | undefined\u003e;\n}\n```\n\n### `isEnvValid(schema, options?)`\n\nCheck if environment is valid without throwing.\n\n```typescript\nimport { isEnvValid } from \"envguards\";\n\nif (!isEnvValid(schema)) {\n  console.error(\"Invalid environment!\");\n  process.exit(1);\n}\n```\n\n### `getEnv(schema, key, options?)`\n\nGet a single validated environment variable value.\n\n```typescript\nimport { getEnv } from \"envguards\";\n\nconst dbUrl = getEnv(schema, \"DATABASE_URL\");\n```\n\n### `generateMarkdown(schema, options?)`\n\nGenerate markdown documentation string.\n\n```typescript\nimport { generateMarkdown } from \"envguards\";\n\nconst markdown = generateMarkdown(schema, {\n  title: \"Environment Variables\",\n});\n```\n\n### `generateEnvExample(schema, options?)`\n\nGenerate `.env.example` content string.\n\n```typescript\nimport { generateEnvExample } from \"envguards\";\n\nconst content = generateEnvExample(schema, {\n  includeComments: true,\n  groupByRequired: false,\n});\n```\n\n### `defineEnvSchema(schema)`\n\nType helper for defining schemas with inference.\n\n```typescript\nimport { defineEnvSchema } from \"envguards\";\n\nexport const envSchema = defineEnvSchema({\n  DATABASE_URL: { required: true },\n});\n```\n\n## Error Messages\n\nWhen validation fails, you get clear, actionable error messages:\n\n```\n❌ Environment validation failed\n\n❌ Missing environment variable: DATABASE_URL\nℹ️  PostgreSQL connection string\n\n❌ Invalid value for NODE_ENV: \"invalid\"\nℹ️  Application environment\n   Allowed values: development, production, test\n```\n\n## CI/CD Integration\n\nUse the `check` command in your CI pipeline:\n\n```yaml\n# GitHub Actions\n- name: Validate environment\n  run: npx envguards check\n  env:\n    DATABASE_URL: ${{ secrets.DATABASE_URL }}\n    JWT_SECRET: ${{ secrets.JWT_SECRET }}\n```\n\n```yaml\n# GitLab CI\nvalidate-env:\n  script:\n    - npx envguards check\n```\n\nThe command exits with code `1` on validation failure, failing your CI build.\n\n## TypeScript Support\n\nenvguards is written in TypeScript and provides full type definitions:\n\n```typescript\nimport type { EnvSchema, EnvVarSchema, ValidationResult } from \"envguards\";\n\nconst schema: EnvSchema = {\n  MY_VAR: {\n    required: true,\n    description: \"My variable\",\n  } satisfies EnvVarSchema,\n};\n```\n\n## Schema File Locations\n\nThe CLI auto-detects schema files in this order:\n\n1. `env.schema.ts`\n2. `env.schema.js`\n3. `env.schema.mjs`\n4. `env.schema.cjs`\n5. `envguard.config.ts`\n6. `envguard.config.js`\n7. `envguard.config.mjs`\n8. `envguard.config.cjs`\n\nOr specify a custom path:\n\n```bash\nnpx envguards generate --schema ./config/env.schema.js\n```\n\n## Contributing\n\nContributions are welcome! Please read our contributing guidelines and submit PRs.\n\n## License\n\nMIT © [Your Name]\n\n---\n\nMade with ❤️ for better developer experience.\n","funding_links":[],"categories":["Development Utilities"],"sub_categories":["Documentation Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprinceofv%2Fenvguards","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprinceofv%2Fenvguards","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprinceofv%2Fenvguards/lists"}