envguardr


Fail-fast CLI to validate environment variables using a strict schema.

envguardr is a lightweight CLI that validates environment variables at build-time or runtime using a schema authored in TypeScript and compiled to JavaScript. Built on top of valitype, it helps catch misconfigurations early and integrate safely into CI/CD pipelines or local builds.

Features

- CLI for validating process.env
- Built with strict runtime types (string, number, boolean, url, enum)
- Support for custom validators with helpful utilities
- Validates required variables or applies defaults
- Fails fast with clear error messages
- Ideal for CI/CD pipelines or local builds

Installation

``bash
npm install --save-dev envguardr
`

Usage

`bash
npx envguardr validate ./env.schema.js
`

You can also add it as a script in your package.json:

`json
"scripts": {
"check-env": "envguardr validate ./env.schema.js"
}
`

$3

`js
import { validators } from 'valitype';

export default {
// Basic types
API_URL: { type: 'url', required: true },
NODE_ENV: {
type: { enum: ['development', 'production'] },
default: 'development'
},
PORT: { type: 'number', default: 3000 },
DEBUG: { type: 'boolean', default: false },
VERSION: { type: 'string', required: true },

// Custom validators
API_KEY: {
type: 'custom',
validator: validators.regex(/^[A-Za-z0-9]{32}$/, 'API_KEY must be a 32-character alphanumeric string'),
required: true
},

CACHE_TTL: {
type: 'custom',
validator: validators.range(0, 86400, 'Cache TTL must be between 0 and 86400 seconds'),
default: '3600'
},

AWS_S3_BUCKET: {
type: 'custom',
validator: validators.awsArn('s3', 'Must be a valid S3 bucket ARN'),
required: true
}
}
`

$3

- Validates all variables defined in the schema
- Fails if any required variable is missing or invalid
- Uses defaults if provided
- Logs output like:

`bash
❌ API_URL is required and must be a valid URL
❌ API_KEY must be a 32-character alphanumeric string
✅ All environment variables are valid.
`

> Returns exit code 1 on failure — perfect for CI pipelines.

Types

`ts
type Rule =
| { type: 'string'; required?: boolean; default?: string }
| { type: 'number'; required?: boolean; default?: number }
| { type: 'boolean'; required?: boolean; default?: boolean }
| { type: 'url'; required?: boolean; default?: string }
| { type: { enum: string[] }; required?: boolean; default?: string }
| { type: 'custom'; validator: CustomValidatorFn; required?: boolean; default?: string; errorMessage?: string }
`

Custom Validators

The library includes several built-in validator utilities:

$3


`typescript
validators.regex(/^[A-Z]{3}$/, 'Must be 3 uppercase letters')
`

$3

`typescript
validators.range(1, 100, 'Value must be between 1 and 100')
`

$3

`typescript
validators.oneOf(['apple', 'banana', 'orange'], 'Must be a valid fruit')
`

$3

`typescript
validators.date('YYYY-MM-DD', 'Must be a valid date')
`

$3

`typescript
validators.json('Must be valid JSON')
`

$3

`typescript
validators.awsArn('lambda', 'Must be a valid Lambda ARN')
`

$3

`typescript
validators.all(
validators.regex(/^[A-Z]/),
validators.oneOf(['Alpha', 'Beta', 'Gamma'])
)
``

Contributing

Contributions are welcome. See CONTRIBUTING.md.

License

This library is licensed under the MIT License. See the LICENSE file for details.