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
- GitHub Actions
- 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

``bash
npm install --save-dev @kitiumai/env-type-generator

or

yarn add -D @kitiumai/env-type-generator

or

pnpm add -D @kitiumai/env-type-generator
`

Quick Start

$3

`env


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
`

$3

`bash
npx env-type-gen
`

$3

`typescript
// 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 & Tree-Shaking

@kitiumai/env-type-generator is designed with optimal tree-shaking in mind. The package is side-effect free ("sideEffects": false) and provides granular subpath exports for minimal bundle size.

$3

Import only what you need to minimize bundle size:

`typescript
// ✅ Granular imports (tree-shakable)
import { GeneratorService } from '@kitiumai/env-type-generator/services/generator-service';
import { EnvParser } from '@kitiumai/env-type-generator/parsers';
import { TypeGenerator } from '@kitiumai/env-type-generator/generators/type-generator';
import { ValidationGenerator } from '@kitiumai/env-type-generator/generators/validation-generator';
import { FileWatcher } from '@kitiumai/env-type-generator/services/file-watcher';
import type { EnvVariable, GeneratorConfig } from '@kitiumai/env-type-generator/types';
import { EnvTypeGeneratorError } from '@kitiumai/env-type-generator/utils/errors';

// ✅ Barrel import (all exports)
import { GeneratorService, EnvParser } from '@kitiumai/env-type-generator';
`

$3

| Subpath | Exports |
| -------------------------------------------------------------- | ------------------------------- |
| @kitiumai/env-type-generator | All exports (barrel) |
| @kitiumai/env-type-generator/generators | TypeGenerator (alias) |
| @kitiumai/env-type-generator/generators/type-generator | TypeGenerator class |
| @kitiumai/env-type-generator/generators/validation-generator | ValidationGenerator class |
| @kitiumai/env-type-generator/parsers | EnvParser class |
| @kitiumai/env-type-generator/services | GeneratorService (alias) |
| @kitiumai/env-type-generator/services/generator-service | GeneratorService class |
| @kitiumai/env-type-generator/services/file-watcher | FileWatcher class |
| @kitiumai/env-type-generator/types | TypeScript types and interfaces |
| @kitiumai/env-type-generator/utils | Error classes (alias) |
| @kitiumai/env-type-generator/utils/errors | Error classes |
| @kitiumai/env-type-generator/logger | Logger utilities |

$3

Use the package programmatically in your build scripts:

`typescript
import { GeneratorService } from '@kitiumai/env-type-generator/services/generator-service';

const generator = new GeneratorService({
envFiles: ['.env', '.env.local'],
outputPath: 'src/types/env.d.ts',
validationLib: 'zod',
validationOutput: 'src/config/env.validator.ts',
parseTypes: true,
strict: true,
});

await generator.generate();
`

Usage

$3

`bash
npx env-type-gen [options]
`

| Option | Description | Default |
| -------------------------------- | ---------------------------------------- | ------------------------------- |
| -e, --env-files | Environment files to parse | .env |
| -o, --output | Output path for type definitions | ./src/types/env.d.ts |
| -v, --validation-lib | Validation library (zod\|yup\|joi\|none) | none |
| -s, --validation-output | Output path for validation schema | ./src/config/env.validator.ts |
| -r, --required | 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 to config file | - |

$3

#### Basic Usage

`bash


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

`bash


Enable type inference (string → number, boolean, etc.)


npx env-type-gen --parse-types
`

This will generate:

`typescript
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

`bash


Generate Zod validation schema


npx env-type-gen --validation-lib zod --parse-types
`

This generates env.validator.ts:

`typescript
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;
export const env = envSchema.parse(process.env);
`

#### With Required Variables

`bash


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

`bash


Auto-regenerate on file changes


npx env-type-gen --watch
`

$3

Create env-type.config.js:

`javascript
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:

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

$3

`typescript
import { GeneratorService } from '@kitiumai/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

$3

`bash


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"
}
}
`

$3

`bash


Generate types

npx env-type-gen --parse-types

Add to package.json

{
"scripts": {
"dev": "env-type-gen && vite",
"build": "env-type-gen && vite build"
}
}
`

$3

`bash


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

$3

Input (.env):

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

Output (env.d.ts):

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

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

$3

Input (.env):

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

Output (env.d.ts):

`typescript
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;
};
`

$3

Input (.env):

`env


Database connection string

DATABASE_URL=postgresql://localhost:5432/mydb

Maximum number of connections

DATABASE_POOL_SIZE=10
`

Output (env.d.ts):

`typescript
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:

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

GitHub Actions

This repository includes comprehensive CI/CD workflows:

$3

Runs on every push and pull request to main/master branch:

- Linting: ESLint and Prettier checks
- Type Checking: TypeScript compilation
- Testing: Multi-version tests (Node 16, 18, 20) across OS (Ubuntu, Windows, macOS)
- Build: Ensures project builds successfully
- Integration Tests: End-to-end CLI testing with type generation and validation

$3

Automatically publishes to npm on GitHub releases:

- Runs all quality checks
- Publishes with npm provenance for enhanced security
- Creates deployment summary

$3

- CodeQL: Weekly security scans for vulnerabilities
- Dependency Review: Automated review on pull requests

$3

Add similar CI/CD to your project using env-type-generator:

`yaml


.github/workflows/ci.yml

name: CI
on: [push, pull_request]

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npx env-type-gen --parse-types
- run: npm test
`

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

$3

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

$3

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

$3

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

Best Practices

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

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

2. Generate in pre-build: Add to your build pipeline

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

3. Use strict mode in production: Catch missing vars early

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

4. Combine with dotenv-expand: For variable interpolation
`env
BASE_URL=https://api.example.com
API_ENDPOINT=${BASE_URL}/v1
``

Contributing

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

License

MIT © kitium-ai

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