Dotenv Types

A CLI tool that validates .env files against a schema and auto-generates TypeScript interfaces for type-safe environment variables in TypeScript projects.

Features

• Schema Validation: Validate .env files against a JSON schema definition
• TypeScript Type Generation: Generate TypeScript interfaces from .env variables
• Strict Type Checking: Required vs optional values with proper type annotations
• Nested Object Support: Parse DB_* prefixed variables into nested objects
• Migration Helper: Analyze existing .env files and generate initial schema

Installation

# Using npm
npm install -g dotenv-types

# Using yarn
yarn global add dotenv-types

# Using pnpm
pnpm add -g dotenv-types

Or run directly with npx:

npx dotenv-types validate

Usage

Validate Command

Validate your .env file against a schema:

dotenv-types validate -e .env -s schema.json

Options:

• -e, --env <path>: Path to .env file (default: .env)
• -s, --schema <path>: Path to schema.json file

Generate Command

Generate TypeScript interfaces from your .env file:

dotenv-types generate -e .env -o env.d.ts

Options:

• -e, --env <path>: Path to .env file (default: .env)
• -s, --schema <path>: Path to schema.json file
• -o, --output <path>: Output file path (stdout if not specified)
• -n, --name <name>: Interface name (default: EnvVariables)

Migrate Command

Generate a schema.json from an existing .env file:

dotenv-types migrate -e .env -o schema.json

Options:

• -e, --env <path>: Path to .env file (default: .env)
• -o, --output <path>: Output file path (default: schema.json)

Configuration

Schema Definition

Create a schema.json file to define your environment variable requirements:

{
  "variables": {
    "PORT": {
      "type": "port",
      "required": true,
      "desc": "Port number for the server"
    },
    "NODE_ENV": {
      "type": "enum",
      "required": true,
      "choices": ["development", "production", "test"],
      "desc": "Environment mode"
    },
    "DATABASE_URL": {
      "type": "url",
      "required": true,
      "desc": "Database connection URL"
    },
    "DEBUG": {
      "type": "boolean",
      "required": false,
      "default": false,
      "desc": "Enable debug mode"
    }
  }
}

Supported Types

Type	Description	Example
string	Any string value	"hello"
number	Decimal number	3.14
int	Integer	42
boolean	true/false	true
port	Valid port number (1-65535)	3000
url	Valid URL	https://api.example.com
email	Valid email	user@example.com
enum	One of specified values	"development"
json	Valid JSON string	{"key": "value"}
host	Valid hostname	localhost

Examples

Basic Usage

1. Create a .env file:

PORT=3000
NODE_ENV=development
DATABASE_URL=postgres://localhost:5432/mydb
DEBUG=true

2. Generate a schema:

dotenv-types migrate -e .env -o schema.json

3. Validate your .env:

dotenv-types validate -e .env -s schema.json

4. Generate TypeScript types:

dotenv-types generate -e .env -o env.d.ts

Generated TypeScript Interface

export interface EnvVariables {
  /** Port number for the server */
  PORT: number;

  /** Environment mode */
  NODE_ENV: 'development' | 'production' | 'test';

  /** Database connection URL */
  DATABASE_URL: string;

  /** Enable debug mode */
  DEBUG?: boolean;  // Default: false
}

Nested Objects

Dotenv Types supports nested objects via underscore notation:

APP_NAME=myapp
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=secret
REDIS_HOST=localhost
REDIS_PORT=6379

Generates:

export interface EnvVariables {
  APP_NAME: string;
  Db?: {
    HOST?: string;
    PORT?: number;
    USER?: string;
    PASSWORD?: string;
  };
  Redis?: {
    HOST?: string;
    PORT?: number;
  };
}

API Reference

JavaScript API

import { parseEnvFile } from 'dotenv-types/core/parser';
import { validateEnv, parseSchemaFromEnv } from 'dotenv-types/core/validator';
import { generateTypeScriptInterface } from 'dotenv-types/utils/typeGenerator';

// Parse .env file
const parsed = parseEnvFile('.env');

// Validate against schema
const schema = parseSchemaFromEnv(parsed.flat);
const result = validateEnv(parsed.flat, schema);

// Generate TypeScript interface
const code = generateTypeScriptInterface(schema, parsed);

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Run CLI locally
npm run dev -- validate -e .env

License

MIT