env-schema-checker

A zero-config, type-safe, schema-driven .env validator with automatic error reporting, autocomplete, and runtime checks.

Features

• ✅ Auto Schema from .env.example
• ✅ TypeScript Autocomplete
• ✅ CLI & API Support
• ✅ Integrates with zod/yup
• ✅ Fails Fast
• ✅ Works with dotenv
• ✅ Safe for SSR/Next.js/NestJS

Installation

npm install env-schema-checker
# or
yarn add env-schema-checker
# or
pnpm add env-schema-checker

Quick Start

import { loadEnv } from 'env-schema-checker';

const env = loadEnv({
  schema: {
    PORT: 'number',
    NODE_ENV: ['development', 'production', 'test'],
    API_KEY: 'string',
  }
});

// TypeScript will provide autocomplete and type checking
app.listen(env.PORT);

CLI Usage

The package includes a command-line interface for easy environment validation and type generation.

Initialize a Schema File

Create a new schema file with default configuration:

# Create default schema file
npx env-schema-checker init

# Create schema file with custom path
npx env-schema-checker init -o ./config/env.schema.json

This creates a .env.schema.json file with default schema:

{
  "NODE_ENV": ["development", "production", "test"],
  "PORT": "number",
  "HOST": "string",
  "DEBUG": "boolean"
}

Validate Environment Variables

Validate your environment variables against a schema:

# Validate using default schema file (.env.schema.json) and .env file
npx env-schema-checker validate

# Validate with custom schema and env file paths
npx env-schema-checker validate -s ./config/schema.json -p ./config/.env

# Validate existing environment variables (no .env file)
npx env-schema-checker validate -s ./config/schema.json

Example Output (Success):

✅ Environment validation successful!

Example Output (Failure):

Environment validation failed:
  PORT: Invalid number format (received: invalid)
  NODE_ENV: Invalid enum value. Expected 'development' | 'production' | 'test', received 'invalid'

Generate TypeScript Types

Generate TypeScript type definitions from your schema:

# Generate types and output to console
npx env-schema-checker gen-types -s .env.schema.json

# Generate types and save to file
npx env-schema-checker gen-types -s .env.schema.json -o ./types/env.d.ts

# Generate types with custom schema path
npx env-schema-checker gen-types -s ./config/schema.json -o ./src/types/env.d.ts

Generated TypeScript Types:

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: 'development' | 'production' | 'test';
      PORT: number;
      HOST: string;
      DEBUG: boolean;
    }
  }
}

export {};

CLI Options

init Command

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

validate Command

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

gen-types Command

• -s, --schema <path> - Path to schema file (default: .env.schema.json)
• -o, --output <path> - Output path for type definitions (optional)

Integration with Build Scripts

Add CLI commands to your package.json scripts:

{
  "scripts": {
    "env:init": "env-schema-checker init",
    "env:validate": "env-schema-checker validate",
    "env:types": "env-schema-checker gen-types -o ./types/env.d.ts",
    "prebuild": "npm run env:validate",
    "build": "npm run env:types && tsc"
  }
}

CI/CD Integration

Use in your CI/CD pipeline to validate environment variables:

# GitHub Actions example
- name: Validate Environment
  run: npx env-schema-checker validate -s .env.schema.json

# Docker example
RUN npx env-schema-checker validate -s .env.schema.json

API Reference

loadEnv(options: LoadEnvOptions)

Loads and validates environment variables according to the provided schema.

interface LoadEnvOptions {
  schema: EnvSchema;
  path?: string;        // Path to .env file
  encoding?: string;    // File encoding
  override?: boolean;   // Override existing env vars
  debug?: boolean;      // Enable debug mode
}

generateTypes(options: TypeGeneratorOptions)

Generates TypeScript type definitions for your environment variables.

interface TypeGeneratorOptions {
  outputPath?: string;  // Path to save type definitions
  schema: EnvSchema;    // Your environment schema
}

validateEnv(schema: EnvSchema)

Validates environment variables without loading them from a file.

parseEnvFile(path: string)

Parses an .env file and returns the variables as an object.

Schema Types

The schema supports the following types:

• 'string' - String values
• 'number' - Numeric values
• 'boolean' - Boolean values
• 'array' - Comma-separated arrays
• 'object' - JSON objects
• string[] - Enum values
• z.ZodType - Custom Zod schemas

Examples

Basic Usage

import { loadEnv } from 'env-schema-checker';

const env = loadEnv({
  schema: {
    PORT: 'number',
    NODE_ENV: ['development', 'production', 'test'],
    API_KEY: 'string',
    DEBUG: 'boolean',
    ALLOWED_ORIGINS: 'array',
    CONFIG: 'object'
  }
});

if (!env.success) {
  console.error('Environment validation failed:', env.errors);
  process.exit(1);
}

// Use validated environment variables
const { PORT, NODE_ENV, API_KEY } = env.env;

Custom Zod Schema

import { z } from 'zod';
import { loadEnv } from 'env-schema-checker';

const env = loadEnv({
  schema: {
    PORT: z.string().transform(Number).pipe(z.number().min(1).max(65535)),
    API_KEY: z.string().min(32),
    DATABASE_URL: z.string().url()
  }
});

Generate Type Definitions

import { generateTypes } from 'env-schema-checker';

const types = generateTypes({
  schema: {
    PORT: 'number',
    NODE_ENV: ['development', 'production', 'test'],
    API_KEY: 'string'
  },
  outputPath: './types/env.d.ts'
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT