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
npm install envconfig-kitimport { 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 missingNo 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 | "[email protected]" |
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" |
const config = env({
NODE_ENV: {
type: 'enum',
values: ['development', 'staging', 'production'] as const,
default: 'development'
},
})
// config.NODE_ENV is typed as 'development' | 'staging' | 'production'const config = env({
ALLOWED_HOSTS: { type: 'array' }, // comma-separated by default
TAGS: { type: 'array', separator: '|' }, // custom separator
})
// config.ALLOWED_HOSTS is string[]const config = env({
FEATURE_FLAGS: { type: 'json' },
})
// Parse JSON from env var: FEATURE_FLAGS='{"darkMode":true}'const config = env({
API_VERSION: {
type: 'regex',
pattern: /^v\d+\.\d+$/
},
})
// Only accepts values like "v1.0", "v2.1"const config = env({
API_KEY: { type: 'string', secret: true },
DATABASE_PASSWORD: { type: 'string', secret: true },
})
// Error messages show **** instead of actual valuesconst config = env({
PORT: {
type: 'number',
validate: (value) => value >= 1024 && value <= 65535
},
})
// Throws if PORT is not in valid rangeimport { 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:
const config = env({
...presets.database('DB_'), // DB_URL, DB_HOST, etc.
...presets.redis('CACHE_'), // CACHE_URL, CACHE_HOST, etc.
})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):
process.env.env.local.env.${NODE_ENV}.env
# Initialize envconfig-kit in your project
npx envconfig-kit init
# Validate .env file
npx envconfig-kit check
# Generate .env.example
npx envconfig-kit generate
# Health check
npx envconfig-kit doctorimport { 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