Configuration

Config file

Create env-typegen.config.ts at your project root:

import { defineConfig } from "@xlameiro/env-typegen";

export default defineConfig({
  input: ".env.example",
  output: "env.generated.ts",
  generators: ["typescript", "zod"],
  format: true,
  schemaFile: "env.contract.ts",
  strict: true,
  diffTargets: [".env", ".env.example", ".env.production"],
  plugins: ["./plugins/custom-validator.mjs"],
});

Practical presets

Generation-focused preset

export default defineConfig({
  input: ".env.example",
  output: "env.generated.ts",
  generators: ["typescript", "zod"],
  format: true,
});

Governance-focused preset

export default defineConfig({
  schemaFile: "env.contract.ts",
  strict: true,
  diffTargets: [".env", ".env.staging", ".env.production"],
});

Monorepo-friendly preset

export default defineConfig({
  input: "apps/web/.env.example",
  output: "apps/web/src/env.generated.ts",
  schemaFile: "config/env.contract.ts",
  diffTargets: ["apps/web/.env", "apps/api/.env", "config/.env.production"],
});

Generate command flags

CLI flags override config file values when both are provided.

Flag	Alias	Description
--input	-i	Path to .env.example file
--output	-o	Output file path
--format	-f	Generator(s): ts, zod, t3, declaration
--generator	-g	Alias for --format
--stdout		Write output to stdout instead of a file
--dry-run		Preview output without writing files
--no-format		Skip Prettier formatting of output
--silent	-s	Suppress all console output
--watch	-w	Re-generate on file changes
--config	-c	Path to config file
--version	-v	Print version
--help	-h	Show help

Validation command flags (check, diff, doctor)

Flag	Commands	Description
--env <path>	check, doctor	Environment source path to validate
--targets <list>	diff, doctor	Comma-separated env targets for drift analysis
--contract <path>	all	Contract file path (env.contract.ts / .mjs / .js)
--example <path>	all	Fallback .env.example used when no contract file is available
--strict	all	Validate extras as errors (default behavior)
--no-strict	all	Downgrade undeclared variables to warnings
--json	all	Emit compact machine-readable JSON report
--json=pretty	all	Emit pretty JSON report
--output-file <path>	all	Persist JSON report to file
--debug-values	all	Include raw values in issues (unsafe for CI logs)
--cloud-provider <name>	all	Add cloud snapshot source: vercel, cloudflare, aws
--cloud-file <path>	all	Cloud snapshot JSON file path
--plugin <path>	all	Plugin module path (repeatable)
--config <path>	all	Config file path
--help	all	Show command help

Precedence model

1. CLI flags (highest priority)
2. Config file values
3. Built-in defaults

Defaults and path resolution

• Strict mode is enabled by default for validation commands.
• diff defaults to .env,.env.example,.env.production when targets are not provided.
• When --contract is omitted, env-typegen auto-discovers env.contract.ts, env.contract.mjs, or env.contract.js.
• All paths are resolved from your current working directory.

FAQ

Should I always commit env-typegen.config.ts?

Yes for team consistency. It centralizes defaults and reduces CI/local mismatch.

Can I use different configs per command?

Yes. Use --config <path> to load command-specific configuration files.