@mpen/env

A lightweight, zero-dependency, type-safe environment variable reader and TypeScript declaration generator.

Features

• Type-Safe Retrieval: Simple helpers to retrieve environment variables as string, boolean, and integer types.
• Auto-Autocomplete: Constrains keys to the global NodeJS.ProcessEnv by default, providing instant IDE autocompletions for augmented environment properties.
• Automatic Generic Inference: Injects and infers custom dictionary keys automatically when instantiating new Environment(rawDict) without requiring manual generic parameters.
• Declaration Generator CLI: Generates highly compatible and strictly typed env.d.ts files from any .env source on-the-fly.

Installation

bun add @mpen/env
# or
npm install @mpen/env

Library Usage

Basic Usage

import { Environment } from '@mpen/env'

// Autocompletes standard and augmented NodeJS.ProcessEnv keys!
const env = new Environment()

const port = env.getInt('PORT', 8080) // returns parsed number, falls back to 8080 if missing/invalid
const debug = env.getBool('DEBUG') // returns boolean (true for 'true', '1', 'yes', etc., false for 'false', '0', etc.)
const host = env.getString('HOST', 'localhost') // returns string, falls back to 'localhost' if missing/empty

Extending ProcessEnv Autocomplete Globally

To get automatic type completions for custom keys when using new Environment(), simply declare an interface augmentation of the ProcessEnv interface inside the global NodeJS namespace anywhere in your project (e.g. src/types/env.d.ts):

declare global {
    namespace NodeJS {
        interface ProcessEnv {
            PORT?: string
            NODE_ENV?: 'development' | 'production' | 'test'
            DATABASE_URL?: string
        }
    }
}

export {}

Custom Dictionaries & Auto Key Inference

Passing a custom dictionary automatically infers the allowed keys for type safety with zero manual generic parameter declarations:

const rawEnv = {
    PORT: '3000',
    HOST: 'localhost',
}

const env = new Environment(rawEnv)

// Autocompletes 'PORT' and 'HOST' perfectly!
const port = env.getInt('PORT')

CLI Type Generator (gen-env-types)

The package includes a highly compatible, zero-dependency CLI gen-env-types to automatically generate env.d.ts declaration maps from .env files.

1. Running on-the-fly (Without Installing)

If you haven't installed the package, you can run the binary directly from npm using its scoped name:

• Using Bun:

  bun x @mpen/env

• Using npm:

  npx @mpen/env

2. Running Locally (Once Installed)

If @mpen/env is installed in your project, you can run the binary directly:

• Using Bun:

  bun x gen-env-types

• Using npm:

  npx gen-env-types

3. Piping and Custom Arguments

By default, the CLI reads from .env in the current directory and outputs the generated types directly to stdout. This matches standard Unix-style piping:

• Generate to a local file (Piped):

  bun x @mpen/env > env.d.ts

• Read a custom environment file and pipe to types:

  bun x @mpen/env .env.production > src/env.d.ts

• Write to a custom file using the output flag (-o):

  bun x @mpen/env .env.production -o src/env.d.ts

Generated Output Example

Reading .env will output clean global script type augmentations:

// Generated by @mpen/env. Do not edit.

declare namespace NodeJS {
    export interface ProcessEnv {
        DEBUG: string
        HOST: string
        NODE_ENV: string
        PORT: string
    }
}

License

MIT