gem-hunter
Language: TypeScript
zod-envkit is a lightweight library and CLI for type-safe environment variables, using Zod to validate process.env, generate docs and examples, and fail fast before deployment — no cloud, no magic, just code.
Type-safe environment variable validation and documentation using Zod.
zod-envkit is a small, explicit library + CLI that treats environment variables as an
explicit runtime contract, not an implicit guessing game.
process.env at startup.env.exampleENV.md, ENV.json, ENV.yaml)zod-envkit init.env* files with priorityNo cloud. No magic. Just code.
Environment variables are critical, but are usually handled poorly.
Typical problems:
process.env is just string | undefined.env.example and docs drift out of synczod-envkit solves this by making env:
Use zod-envkit if:
.env.example and docs from a single source of truthSkip zod-envkit if:
npm install zod-envkit yarn add zod-envkit pnpm add zod-envkit bun add zod-envkit
Create a single file responsible for loading and validating env.
import "dotenv/config"; import { z } from "zod"; import { loadEnv, mustLoadEnv, formatZodError } from "zod-envkit"; const EnvSchema = z.object({ NODE_ENV: z.enum(["development", "test", "production"]), PORT: z.coerce.number().int().min(1).max(65535), DATABASE_URL: z.string().url(), });
const result = loadEnv(EnvSchema); if (!result.ok) { console.error("Invalid environment:\n" + formatZodError(result.error)); process.exit(1); } export const env = result.env;
export const env = mustLoadEnv(EnvSchema);
Now:
env.PORT is a numberenv.DATABASE_URL is a stringThe CLI works from a metadata file: env.meta.json.
By default, it is searched in:
./env.meta.json./examples/env.meta.json{
"NODE_ENV": {
"description": "Runtime mode",
"example": "development",
"required": true
},
"PORT": {
"description": "HTTP port",
"example": "3000",
"required": true
},
"DATABASE_URL": {
"description": "Postgres connection string",
"example": "postgresql://user:pass@localhost:5432/db",
"required": true
}
}(Default behavior)
npx zod-envkit
or explicitly:
npx zod-envkit generate
Generate docs in different formats:
npx zod-envkit generate --format json npx zod-envkit generate --format yaml
Control sorting:
npx zod-envkit generate --sort alpha npx zod-envkit generate --sort required-first
Loads dotenv files, masks secrets, and displays a readable table.
npx zod-envkit show
Advanced options:
npx zod-envkit show --mask-mode full
npx zod-envkit show --no-mask
npx zod-envkit show --dotenv ".env,.env.local,.env.production"npx zod-envkit check
Strict mode (fail on unknown variables):
npx zod-envkit check --strict
Production guard (stricter deploy/CI checks; unknown dotenv keys fail like --strict):
npx zod-envkit check --production
1 if required variables are missing--strict mode also fails on unknown variables (dotenv-loaded keys only)--production also fails on unknown dotenv variables (same dotenv-only scope as --strict)--production also fails when a required dotenv key is present but empty after trim (PORT=, PORT=" ")--production also fails on placeholder stubs (meta example match, changeme/todo/xxx, <...>, YOUR_*_HERE)Bootstrap configuration from existing files.
Generate env.meta.json from .env.example:
npx zod-envkit init
Generate .env.example from existing metadata:
npx zod-envkit init --from-meta
zod-envkit follows Semantic Versioning.
Everything listed below is treated as stable public API for the whole 1.x line.
Library exports (entrypoint zod-envkit):
loadEnvmustLoadEnvformatZodErrorcheckEnvgetMissingEnvgetUnknownEnvisSecretKeygenerateEnvExamplegenerateEnvDocssortMetaEntriesEnvMeta, EnvMetaEntry, EnvCheckResult, GenerateDocsOptions, DocsFormat, SortModeCLI contract:
generate, show, check, init0, user error = 1)A breaking change (major) includes:
zod-envkit does with no args)A non-breaking change (minor/patch) includes:
env.meta.jsonVersion 1.2.0 focuses on reliability, contract enforcement, and CI readiness.
Highlights:
check --strict) for CI usageshowThis is the point where zod-envkit stops being “just a helper” and becomes a
stable environment contract tool for CI/CD pipelines.
dotenv:
zod-envkit:
They are designed to be used together.
MIT