Validation & Governance

Why validation matters

Generation alone keeps types in sync, but production issues often come from environment drift. Validation commands let you enforce contracts before deployment.

Command decision guide

Command	Best when	Output style
check	You want to validate one source against a contract	Pass/fail findings for one source
diff	You need parity across multiple sources	Drift report across targets
doctor	You want one consolidated diagnostic report	Combined findings + recommendations

Contract file

By default, env-typegen auto-discovers env.contract.ts, env.contract.mjs, or env.contract.js.

export default {
  schemaVersion: 1,
  variables: {
    PORT: { expected: { type: "number" }, required: true, clientSide: false },
    NEXT_PUBLIC_APP_URL: { expected: { type: "url" }, required: true, clientSide: true },
    APP_VERSION: { expected: { type: "semver" }, required: true, clientSide: false },
  },
};

If no contract file is found, env-typegen can bootstrap from .env.example.

Usage examples

# Validate one source
env-typegen check --env .env --contract env.contract.ts

# Compare drift across standard targets
env-typegen diff --targets .env,.env.example,.env.production --contract env.contract.ts

# Aggregate diagnostics
env-typegen doctor --env .env --targets .env,.env.example,.env.production --contract env.contract.ts

CI pipeline pattern

# Pull request check
env-typegen check --env .env --contract env.contract.ts --json --output-file reports/env-check.json

# Release gate drift scan
env-typegen diff --targets .env,.env.staging,.env.production --contract env.contract.ts --json=pretty --output-file reports/env-drift.json

Strict mode

• Strict mode is enabled by default.
• Use --no-strict to downgrade undeclared variables to warnings.

JSON output for CI

# Compact JSON
env-typegen check --env .env --json

# Pretty JSON + file output
env-typegen check --env .env --json=pretty --output-file reports/env-check.json

Cloud snapshot sources

Use provider snapshots as validation inputs:

env-typegen check --cloud-provider vercel --cloud-file vercel-env.json --contract env.contract.ts
env-typegen diff --cloud-provider cloudflare --cloud-file cloudflare-env.json --contract env.contract.ts
env-typegen doctor --cloud-provider aws --cloud-file aws-env.json --contract env.contract.ts

Supported providers: vercel, cloudflare, aws.

Plugins

Plugins can transform contract, source values, and final report.

export default {
  name: "report-plugin",
  transformReport: (report) => ({
    ...report,
    recommendations: [...(report.recommendations ?? []), "plugin-applied"],
  }),
};

Load them via --plugin flags or plugins in env-typegen.config.ts.

All validation paths (--env, --contract, --targets, --cloud-file, --output-file) are resolved from your current working directory.

FAQ

Should I run check and diff, or only doctor?

Use doctor when you want one command for diagnostics. Use check and diff separately when your CI has stage-specific gates.

Can I include sensitive values in JSON reports?

Only when intentionally debugging. Use --debug-values with care because values may leak into logs.

Do cloud snapshots replace local .env checks?

No. They complement local checks and help detect cross-environment drift before rollout.