You deployed. An env var was missing. Prod crashed at 3am.
envguardr stops that before it happens.
$ npx envguardr validate ./env.schema.js
❌ API_URL is required
❌ PORT must be a valid number
✅ All environment variables are valid.Blocks bad deploys
Fails CI before a misconfigured app ever reaches production. Exits with code 1 on failure.
Strict by design
Rejects 1e5, yes, on — no silent type coercion surprises.
Zero config overhead
One plain JS file, no classes, decorators, or build steps required.
Works everywhere
npm script, CI step, Docker image (amd64 + arm64), or npx.
No telemetry
Validation runs locally. Environment data never leaves your machine.
Supply chain transparency
Signed images, SBOM, and provenance — fully auditable end to end.
v3 receives security fixes only, for six months after the release of v4.0.0. See the v4 documentation and its migration guide.
Quick start
Create an env.schema.js file:
export default {
API_URL: { type: 'url', required: true },
PORT: { type: 'number', default: 3000 },
NODE_ENV: {
type: { enum: ['development', 'production', 'test'] },
default: 'development',
},
}
Run validation:
npx envguardr validate ./env.schema.js
Install
npm install --save-dev envguardr
Schema
Schemas are plain JavaScript modules with full access to built-in validators:
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
- name: Validate environment
run: npx envguardr validate ./env.schema.js
Or as an npm script:
{
"scripts": {
"check-env": "envguardr validate ./env.schema.js"
}
}
Docker
docker run --rm \
--env-file .env \
-v "$PWD:/app" \
docker.io/fontebasso/envguardr validate ./env.schema.js
| Platform | Status |
|---|---|
linux/amd64 |
Supported |
linux/arm64 |
Supported |
Validation types
| Type | Accepts | Notes |
|---|---|---|
string |
Any string | |
number |
"3000" |
Decimal only; rejects 0xff, 1e5 |
boolean |
"true" / "false" |
Strict; rejects 1, yes, on |
url |
"https://..." |
Requires http or https |
{ enum: string[] } |
One listed value | |
custom |
Custom validator |
All types support required and default.
Built-in validators
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']))
Security & supply chain
- npm Trusted Publishing with provenance (OIDC-based, no long-lived tokens)
- Docker images with provenance and SBOM
- Signed images via cosign / Sigstore (keyless, OIDC)
- Distroless, non-root containers
- GitHub Actions pinned by SHA
- CodeQL scanning enabled
Verifying container images
cosign verify \
--certificate-identity-regexp "https://github.com/fontebasso/envguardr/.github/workflows/.*" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
docker.io/fontebasso/envguardr:latest
To report a vulnerability, see SECURITY.md.