Install

npm i @aman179102/typeenv

Zero external dependencies. Works with Node.js 18+, Bun, and Deno.

Quick Start

1. Define your schema

{
  "type": "object",
  "properties": {
    "DATABASE_URL": {
      "type": "string",
      "description": "Database connection string",
      "required": true
    },
    "PORT": {
      "type": "number",
      "default": 3000,
      "minimum": 1024,
      "maximum": 65535
    },
    "NODE_ENV": {
      "type": "string",
      "enum": ["development", "production", "test"],
      "default": "development"
    },
    "API_KEY": {
      "type": "string",
      "required": true,
      "sensitive": true
    }
  },
  "required": ["DATABASE_URL", "API_KEY"]
}

2. Use in code

import { createEnv } from '@aman179102/typeenv';

const env = createEnv({ schema: './env.schema.json' });

// Fully typed with autocomplete
console.log(env.DATABASE_URL); // string
console.log(env.PORT);         // number (auto-coerced from string)
console.log(env.NODE_ENV);     // 'development' | 'production' | 'test'
console.log(env.API_KEY);      // string (masked in error logs)

CLI (optional)

npx @aman179102/typeenv-cli init        # Create env.schema.json
npx @aman179102/typeenv-cli generate    # .env.example + env.d.ts
npx @aman179102/typeenv-cli check       # Validate .env against schema

Why typeenv?

| Feature | typeenv | dotenv | envalid | @t3-oss/env | |---------|---------|--------|---------|-------------| | Zero dependencies | ✅ | ✅ | ✅ | ❌ (needs Zod) | | TypeScript types | ✅ | ❌ | ❌ | ✅ | | Auto .env.example | ✅ | ❌ | ❌ | ❌ | | Auto env.d.ts | ✅ | ❌ | ❌ | ❌ | | JSON Schema → types | ✅ | ❌ | ❌ | ❌ | | CI validation | ✅ | ❌ | ❌ | ❌ | | Secret masking | ✅ | ❌ | ❌ | ❌ | | Framework agnostic | ✅ | ✅ | ✅ | ❌ (Next.js) |

API Reference

createEnv(config)

const env = createEnv({
  schema: './env.schema.json',  // Path or inline object
  strict: true,                  // Throw on missing required (default: true)
  prefix: 'MY_APP_',            // Filter by prefix (optional)
});

validateEnv(env, schema)

import { validateEnv } from '@aman179102/typeenv';

const result = validateEnv(process.env, schema);
result.valid;    // boolean
result.errors;   // ValidationError[]

generateEnvExample(schema)

import { generateEnvExample } from '@aman179102/typeenv';

const content = generateEnvExample(schema);
// → string for .env.example

generateTypeDefinitions(schema)

import { generateTypeDefinitions } from '@aman179102/typeenv';

const types = generateTypeDefinitions(schema);
// → string for env.d.ts

Schema Fields

| Field | Type | Description | |-------|------|-------------| | type | string \| number \| boolean \| integer | Value type | | required | boolean | Variable is mandatory | | default | string \| number \| boolean | Default if not set | | description | string | Human-readable help text | | pattern | string (regex) | Regex validation | | enum | array | Allowed values | | minimum / maximum | number | Range (number/integer) | | minLength / maxLength | number | String length limits | | sensitive | boolean | Mask in error messages |

Examples

Express.js

import { createEnv } from '@aman179102/typeenv';

const env = createEnv({ schema: './env.schema.json' });

app.listen(env.PORT, () => {
  console.log(`Server on port ${env.PORT}`);
});

Inline schema

const env = createEnv({
  schema: {
    type: 'object',
    properties: {
      PORT: { type: 'number', default: 3000 },
      NODE_ENV: { type: 'string', enum: ['dev', 'prod'], default: 'dev' },
    },
    required: [],
  },
});

License

MIT