Type-safe environment variables with fail-fast validation
npm install envconfig-kit> Type-safe environment variables with fail-fast validation. Zero dependencies.






- Built-in .env loading - no need for dotenv
- Type-safe - full TypeScript inference
- Zero dependencies - ~3KB minified
- Fail-fast validation - catches errors at startup
- Actionable error messages - tells you exactly how to fix issues
- Framework presets - common patterns for database, redis, auth
- Secret masking - hide sensitive values in error messages
- Custom validation - add your own validation logic
``bash`
npm install envconfig-kit
`typescript
import { env } from 'envconfig-kit'
const config = env({
PORT: { type: 'number', default: 3000 },
API_KEY: { type: 'string', secret: true },
DEBUG: { type: 'boolean', default: false },
DATABASE_URL: { type: 'url' },
})
// config.PORT is typed as number
// config.API_KEY is typed as string
// Throws on startup if API_KEY or DATABASE_URL is missing
`
No need for dotenv - envconfig-kit automatically loads .env files.
| Type | Validates | Example |
|------|-----------|---------|
| string | Any string | "hello" |number
| | Valid number | "3.14" → 3.14 |integer
| | Whole numbers only | "42" → 42 |boolean
| | true/false, 1/0, yes/no | "true" → true |url
| | Valid URL with protocol | "https://api.example.com" |email
| | Valid email format | "user@example.com" |port
| | Number between 0-65535 | "3000" → 3000 |json
| | Valid JSON string | '{"key":"value"}' → {key: "value"} |array
| | Comma-separated values | "a,b,c" → ["a", "b", "c"] |enum
| | One of allowed values | "production" |regex
| | Matches pattern | "ABC-123" |
`typescript`
const config = env({
NODE_ENV: {
type: 'enum',
values: ['development', 'staging', 'production'] as const,
default: 'development'
},
})
// config.NODE_ENV is typed as 'development' | 'staging' | 'production'
`typescript`
const config = env({
ALLOWED_HOSTS: { type: 'array' }, // comma-separated by default
TAGS: { type: 'array', separator: '|' }, // custom separator
})
// config.ALLOWED_HOSTS is string[]
`typescript`
const config = env({
FEATURE_FLAGS: { type: 'json' },
})
// Parse JSON from env var: FEATURE_FLAGS='{"darkMode":true}'
`typescript`
const config = env({
API_VERSION: {
type: 'regex',
pattern: /^v\d+\.\d+$/
},
})
// Only accepts values like "v1.0", "v2.1"
`typescript`
const config = env({
API_KEY: { type: 'string', secret: true },
DATABASE_PASSWORD: { type: 'string', secret: true },
})
// Error messages show ** instead of actual values
`typescript`
const config = env({
PORT: {
type: 'number',
validate: (value) => value >= 1024 && value <= 65535
},
})
// Throws if PORT is not in valid range
`typescript
import { env, presets } from 'envconfig-kit'
const config = env({
...presets.server(), // PORT, HOST, NODE_ENV
...presets.database(), // DATABASE_URL, DATABASE_HOST, etc.
...presets.redis(), // REDIS_URL, REDIS_HOST, etc.
...presets.auth(), // AUTH_JWT_SECRET, etc.
...presets.aws(), // AWS_ACCESS_KEY_ID, etc.
...presets.smtp(), // SMTP_HOST, SMTP_PORT, etc.
...presets.cors(), // CORS_ORIGINS, CORS_METHODS, etc.
})
`
Custom prefixes:
`typescript`
const config = env({
...presets.database('DB_'), // DB_URL, DB_HOST, etc.
...presets.redis('CACHE_'), // CACHE_URL, CACHE_HOST, etc.
})
`typescript`
env({
// Required string
API_KEY: { type: 'string' },
// With default value
PORT: { type: 'number', default: 3000 },
// Optional (can be undefined)
OPTIONAL_VAR: { type: 'string', optional: true },
// Secret (masked in errors)
PASSWORD: { type: 'string', secret: true },
// With transform
TAGS: {
type: 'array',
transform: (arr) => arr.map(s => s.toUpperCase())
},
// With custom validation
COUNT: {
type: 'integer',
validate: (n) => n > 0 && n < 100
},
})
When validation fails, you get clear errors with fix suggestions:
`
❌ Environment validation failed:
API_KEY: Missing required environment variable
➜ Fix: Add to .env file
Example: API_KEY=your-value-here
PORT: Invalid number: "abc"
➜ Fix: Provide a valid number
Example: PORT=3000
Run your app with valid environment variables or add them to .env
`
envconfig-kit automatically loads environment variables from:
- .env.env.local
- .env.${NODE_ENV}
- (e.g., .env.development, .env.production)
Priority order (highest to lowest):
1. process.env.env.local
2. .env.${NODE_ENV}
3. .env
4.
`bashInitialize envconfig-kit in your project
npx envconfig-kit init
Export Schema
`typescript
import { schemaToMarkdown, schemaToJSON, generateDotenvExample } from 'envconfig-kit'const schema = {
PORT: { type: 'number', default: 3000 },
API_KEY: { type: 'string' },
}
// Generate markdown table for docs
console.log(schemaToMarkdown(schema))
// Generate .env.example
console.log(generateDotenvExample(schema))
// Export as JSON
console.log(schemaToJSON(schema))
``MIT