https://github.com/fontebasso/envguardr
Catch broken env vars before your app starts — fail-fast CLI with strict schema validation.
https://github.com/fontebasso/envguardr
ci cli devops dotenv env environment-variables fail-fast schema typescript validation
Last synced: about 17 hours ago
JSON representation
Catch broken env vars before your app starts — fail-fast CLI with strict schema validation.
- Host: GitHub
- URL: https://github.com/fontebasso/envguardr
- Owner: fontebasso
- License: mit
- Created: 2025-05-10T16:17:00.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-06-28T04:58:23.000Z (1 day ago)
- Last Synced: 2026-06-28T05:13:54.395Z (1 day ago)
- Topics: ci, cli, devops, dotenv, env, environment-variables, fail-fast, schema, typescript, validation
- Language: TypeScript
- Homepage:
- Size: 236 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://github.com/fontebasso/envguardr/actions/workflows/tests.yml)
[](https://www.npmjs.com/package/envguardr)
[](https://www.npmjs.com/package/envguardr)
[](https://www.npmjs.com/package/envguardr)
[](LICENSE)
**Catch broken env vars before your app starts.**
```bash
npx envguardr validate ./env.schema.js
```
```
❌ API_URL is required
❌ PORT must be a valid number
✅ All environment variables are valid.
```
Exits with code `1` on failure — drop it into any CI pipeline and ship with confidence.
---
## Install
```bash
npm install --save-dev envguardr
```
## Schema
```js
// env.schema.js
import { validators } from 'valitype';
export default {
API_URL: { type: 'url', required: true },
PORT: { type: 'number', default: 3000 },
NODE_ENV: { type: { enum: ['development', 'production', 'test'] }, default: 'development' },
DEBUG: { type: 'boolean', default: false },
API_KEY: {
type: 'custom',
validator: validators.regex(/^[A-Za-z0-9]{32}$/, 'Must be 32 alphanumeric characters'),
required: true,
},
}
```
## CI/CD
```yaml
- name: Validate environment
run: npx envguardr validate ./env.schema.js
```
Or as an npm script:
```json
"scripts": {
"check-env": "envguardr validate ./env.schema.js"
}
```
## Node.js support
`envguardr` supports the following Node.js versions:
| Node.js | Status |
| ------- | --------- |
| 20 | Supported |
| 22 | Supported |
| 24 | Supported |
The test suite runs against all supported Node.js versions to ensure compatibility across the supported runtime matrix.
## Types
| Type | Accepts | Notes |
|---|---|---|
| `string` | Any string | |
| `number` | `"3000"` | Decimal only — rejects `0xff`, `1e5` |
| `boolean` | `"true"` / `"false"` | Strict — no `1`, `yes`, `on` |
| `url` | `"https://..."` | Requires `http` or `https` |
| `{ enum: string[] }` | One of the listed values | |
| `custom` | — | Bring your own logic |
All types accept `required?: boolean` and `default?: T`.
## Built-in validators
```ts
validators.regex(/^[A-Z]{3}$/, 'Must be 3 uppercase letters')
validators.range(1, 65535, 'Must be a valid port')
validators.oneOf(['us-east-1', 'eu-west-1'], 'Unsupported region')
validators.date('YYYY-MM-DD', 'Invalid date format')
validators.json('Must be valid JSON')
validators.awsArn('lambda', 'Must be a valid Lambda ARN')
validators.all(validators.regex(/^[A-Z]/), validators.oneOf(['Alpha', 'Beta']))
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
MIT — see [LICENSE](LICENSE).