Getting Started

Installation

pnpm add -D @xlameiro/env-typegen

1) Generate your first typed output

env-typegen --input .env.example --output env.generated.ts --format ts

This command gives you a typed environment contract directly from .env.example.

2) Generate multiple outputs from one source

env-typegen -i .env.example -o env.generated.ts -f ts -f zod -f t3 -f declaration

When multiple formats are specified, each generator writes a separate file:

• env.generated.typescript.ts
• env.generated.zod.ts
• env.generated.t3.ts
• env.generated.d.ts

3) Enable watch mode during local development

Automatically re-generates on every change to your .env.example:

env-typegen -i .env.example -o env.generated.ts -f ts --watch

4) Create a validation contract

Create env.contract.ts in your project root:

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

5) Validate environment files against that contract

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

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

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

6) Export JSON output for CI pipelines

env-typegen check --env .env --json --output-file reports/env-check.json

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

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

Recommended rollout path

1. Start with generation-only (ts + zod) to remove manual typing.
2. Add check in CI to enforce required variables and types.
3. Add diff and doctor to prevent drift between environments.
4. Add cloud snapshots and plugins only when your team needs them.

FAQ

Do I need all generators from day one?

No. You can start with one format and add more over time with repeated --format flags.

What if I do not have env.contract.ts yet?

env-typegen can bootstrap from .env.example, but explicit contracts are recommended for governance.