env-type-generator

env-type-generator

Zero-config TypeScript type generator for .env files with Zod validation, watch mode, and IDE autocomplete

Stop writing types for process.env manually. Let env-type-generator do it for you!

Table of Contents

• Features
• Installation
• Quick Start
• Usage
• Examples
• Framework Integration
• CI/CD Integration
• Configuration
• API
• Troubleshooting
• Contributing
• License

Features

• ✅ Zero Config - Works out of the box with sensible defaults
• ✅ Auto-Generation - Generates TypeScript types from existing .env files
• ✅ Type Inference - Optionally infer types (string, number, boolean, object)
• ✅ Runtime Validation - Generate Zod/Yup/Joi schemas for runtime validation
• ✅ Watch Mode - Auto-regenerate on file changes
• ✅ Multiple Files - Support for .env, .env.local, .env.production, etc.
• ✅ Framework Agnostic - Works with any TypeScript project
• ✅ IDE Autocomplete - Get IntelliSense for process.env

Installation

npm install --save-dev env-type-generator

# or
yarn add -D env-type-generator

# or
pnpm add -D env-type-generator

Quick Start

1. Create your .env file

# Database
DATABASE_URL=postgresql://localhost:5432/mydb
DATABASE_POOL_SIZE=10

# API Keys
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_PUBLISHABLE_KEY=pk_test_xxx

# Features
ENABLE_ANALYTICS=true
MAX_UPLOAD_SIZE_MB=50

2. Generate types

npx env-type-gen

3. Use type-safe environment variables

// TypeScript knows about your env vars!
const dbUrl: string = process.env.DATABASE_URL; // Autocomplete works!
const poolSize: number = env.DATABASE_POOL_SIZE; // Parsed as number

// ❌ TypeScript will catch typos
const invalid = process.env.DATABSE_URL; // Error: Property 'DATABSE_URL' does not exist

Usage

CLI Options

npx env-type-gen [options]

Option	Description	Default
-e, --env-files <files...>	Environment files to parse	.env
-o, --output <path>	Output path for type definitions	./src/types/env.d.ts
-v, --validation-lib <library>	Validation library (zod|yup|joi|none)	none
-s, --validation-output <path>	Output path for validation schema	./src/config/env.validator.ts
-r, --required <vars...>	Required environment variables	[]
-p, --parse-types	Parse and infer types from values	false
-t, --strict	Treat all variables as required	false
-w, --watch	Watch mode - regenerate on file changes	false
-c, --config <path>	Path to config file	-

Examples

Basic Usage

# Generate types from .env
npx env-type-gen

# Specify custom output path
npx env-type-gen --output ./types/env.d.ts

# Parse multiple env files
npx env-type-gen --env-files .env .env.local

With Type Inference

# Enable type inference (string → number, boolean, etc.)
npx env-type-gen --parse-types

This will generate:

declare namespace NodeJS {
  interface ProcessEnv {
    DATABASE_URL?: string | undefined;
    DATABASE_POOL_SIZE?: number | undefined;  // ← Inferred as number
    ENABLE_ANALYTICS?: boolean | undefined;    // ← Inferred as boolean
  }
}

With Zod Validation

# Generate Zod validation schema
npx env-type-gen --validation-lib zod --parse-types

This generates env.validator.ts:

import { z } from 'zod';

export const envSchema = z.object({
  DATABASE_URL: z.string().optional(),
  DATABASE_POOL_SIZE: z.string().transform((val) => Number(val)).optional(),
  ENABLE_ANALYTICS: z.enum(["true", "false"]).transform((val) => val === "true").optional(),
});

export type Env = z.infer<typeof envSchema>;
export const env = envSchema.parse(process.env);

With Required Variables

# Mark specific variables as required
npx env-type-gen --required DATABASE_URL STRIPE_SECRET_KEY

# Or mark ALL variables as required (strict mode)
npx env-type-gen --strict

Watch Mode

# Auto-regenerate on file changes
npx env-type-gen --watch

Configuration File

Create env-type.config.js:

module.exports = {
  envFiles: ['.env', '.env.local'],
  outputPath: './src/types/env.d.ts',
  validationLib: 'zod',
  validationOutput: './src/config/env.validator.ts',
  requiredVars: ['DATABASE_URL', 'API_KEY'],
  parseTypes: true,
  strict: false,
};

Then run:

npx env-type-gen --config env-type.config.js

Programmatic API

import { GeneratorService } from 'env-type-generator';

const service = new GeneratorService();

await service.generate({
  envFiles: ['.env'],
  outputPath: './types/env.d.ts',
  parseTypes: true,
  validationLib: 'zod',
  validationOutput: './config/env.validator.ts',
});

🎨 Framework Integration

Next.js

# Generate types
npx env-type-gen --env-files .env.local .env --parse-types

# Add to package.json
{
  "scripts": {
    "dev": "env-type-gen && next dev",
    "build": "env-type-gen && next build"
  }
}

Vite

# Generate types
npx env-type-gen --parse-types

# Add to package.json
{
  "scripts": {
    "dev": "env-type-gen && vite",
    "build": "env-type-gen && vite build"
  }
}

Node.js / Express

# Generate with Zod validation
npx env-type-gen --validation-lib zod --parse-types --strict

# Use in your app
import { env } from './config/env.validator';

const app = express();
app.listen(env.PORT); // Type-safe!

📝 Generated Output Examples

Without Type Parsing

Input (.env):

DATABASE_URL=postgresql://localhost:5432/mydb
PORT=3000

Output (env.d.ts):

declare namespace NodeJS {
  interface ProcessEnv {
    DATABASE_URL?: string | undefined;
    PORT?: string | undefined;
  }
}

export declare const env: {
  DATABASE_URL?: string;
  PORT?: string;
};

With Type Parsing

Input (.env):

DATABASE_URL=postgresql://localhost:5432/mydb
PORT=3000
ENABLE_DEBUG=true
CONFIG={"key":"value"}

Output (env.d.ts):

declare namespace NodeJS {
  interface ProcessEnv {
    DATABASE_URL?: string | undefined;
    PORT?: number | undefined;
    ENABLE_DEBUG?: boolean | undefined;
    CONFIG?: object | undefined;
  }
}

export declare const env: {
  DATABASE_URL?: string;
  PORT?: number;
  ENABLE_DEBUG?: boolean;
  CONFIG?: object;
};

With Comments

Input (.env):

# Database connection string
DATABASE_URL=postgresql://localhost:5432/mydb

# Maximum number of connections
DATABASE_POOL_SIZE=10

Output (env.d.ts):

declare namespace NodeJS {
  interface ProcessEnv {
    /** Database connection string */
    DATABASE_URL?: string | undefined;

    /** Maximum number of connections */
    DATABASE_POOL_SIZE?: number | undefined;
  }
}

TypeScript Configuration

Add the generated types to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["node"],
    "typeRoots": ["./node_modules/@types", "./src/types"]
  },
  "include": ["src/**/*", "src/types/env.d.ts"]
}

Comparison with Other Tools

Feature	env-type-generator	t3-env	envalid	ts-dotenv
Auto-generate from .env	✅	❌	❌	❌
Zero config	✅	❌	❌	❌
Type inference	✅	⚠️	⚠️	✅
Runtime validation	✅	✅	✅	✅
Framework-agnostic	✅	❌	✅	✅
Watch mode	✅	❌	❌	❌
Active maintenance	✅	✅	✅	❌
Weekly downloads	TBD	501K	200K	3.6K

Key Advantage: We're the only tool that auto-generates types from existing .env files without requiring manual schema definition.

🛠️ Troubleshooting

Types not updating in IDE

• Restart TypeScript server: Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"
• Ensure env.d.ts is included in tsconfig.json

Variables not being recognized

• Check that your .env file uses valid variable names (UPPERCASE_WITH_UNDERSCORES)
• Regenerate types: npx env-type-gen
• Verify output path matches your tsconfig includes

Watch mode not working

• Ensure you have write permissions in the output directory
• Check that the .env file path is correct
• Try using absolute paths instead of relative paths

Best Practices

• Add to git ignore: Add generated files to .gitignore

  src/types/env.d.ts
  src/config/env.validator.ts
  

• Generate in pre-build: Add to your build pipeline

  {
    "scripts": {
      "prebuild": "env-type-gen",
      "build": "tsc"
    }
  }
  

• Use strict mode in production: Catch missing vars early

  env-type-gen --strict --required DATABASE_URL API_KEY
  

• Combine with dotenv-expand: For variable interpolation

  BASE_URL=https://api.example.com
  API_ENDPOINT=${BASE_URL}/v1
  

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © ashishyd

Acknowledgments

• Inspired by t3-env and envalid
• Built with TypeScript, Commander, Chokidar, and Zod

Support

• Report issues
• Discussions
• Star on GitHub

Made with ❤️ for the TypeScript community