@yarlis/config

Type-safe configuration management with Zod validation, feature flags, and multi-environment support.

Installation

npm install @yarlis/config
npm install zod # peer dependency

Quick Start

import { defineConfig, createEnv, featureFlag, z } from '@yarlis/config'

// 1. Define app configuration
const appConfig = defineConfig({
  app: 'my-saas',
  version: '1.0.0',
  env: process.env.NODE_ENV || 'development',
  debug: true
})

// 2. Validate environment variables
const env = createEnv({
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(1),
  PORT: z.string().transform(Number).pipe(z.number().positive())
})

// 3. Use feature flags
if (featureFlag('new-dashboard', false)) {
  // New dashboard code
}

Environment Validation

Create type-safe environment variables with automatic validation:

import { createEnv, z } from '@yarlis/config'

const env = createEnv({
  // Required string
  DATABASE_URL: z.string().url(),
  
  // Optional with default
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
  
  // Transform types
  PORT: z.string().transform(Number).pipe(z.number().positive()),
  MAX_CONNECTIONS: z.string().transform(Number).pipe(z.number().int().positive()),
  
  // Boolean flags
  ENABLE_METRICS: z.string().transform(val => val === 'true').pipe(z.boolean())
})

// Now env is fully typed and validated
console.log(env.DATABASE_URL) // string (validated URL)
console.log(env.PORT) // number

Feature Flags

Control features per environment with type-safe flags:

import { featureFlag, setFeatureFlag } from '@yarlis/config'

// Simple flag with default
const isEnabled = featureFlag('new-ui', false)

// Environment-specific flags
setFeatureFlag({
  name: 'premium-features',
  enabled: true,
  environments: ['production', 'staging'],
  metadata: { rollout: '50%' }
})

// Check flag (returns false in development, true in production/staging)
if (featureFlag('premium-features')) {
  // Premium features code
}

Configuration Management

import { defineConfig, getConfig, getAllConfig } from '@yarlis/config'

// Define configuration
defineConfig({
  app: 'my-saas',
  database: {
    pool: { min: 2, max: 10 },
    timeout: 5000
  },
  features: {
    analytics: true,
    notifications: false
  }
})

// Access configuration
const dbConfig = getConfig('database')
const allConfig = getAllConfig()

Real-World Example

// config/app.ts
import { defineConfig, createEnv, featureFlag, z } from '@yarlis/config'

// Environment validation
export const env = createEnv({
  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  OPENAI_API_KEY: z.string().optional(),
  STRIPE_SECRET_KEY: z.string().optional(),
  SENTRY_DSN: z.string().url().optional()
})

// App configuration
export const config = defineConfig({
  app: 'MyBotBox',
  version: '2.0.0',
  env: env.NODE_ENV,
  debug: env.NODE_ENV === 'development',
  
  database: {
    url: env.DATABASE_URL,
    pool: { min: 2, max: 20 },
    timeout: 30000
  },
  
  redis: {
    url: env.REDIS_URL,
    ttl: 3600
  },
  
  auth: {
    jwtSecret: env.JWT_SECRET,
    tokenExpiry: '7d'
  }
})

// Feature flags
export const features = {
  aiChat: featureFlag('ai-chat', true, ['production', 'staging']),
  betaFeatures: featureFlag('beta-features', false, ['staging']),
  analytics: featureFlag('analytics', env.NODE_ENV === 'production'),
  newDashboard: featureFlag('new-dashboard', false)
}

// Usage in your app
if (features.aiChat && env.OPENAI_API_KEY) {
  // Initialize AI chat
}

Environment Files

Create .env files for different environments:

# .env.development
NODE_ENV=development
DATABASE_URL=postgresql://localhost:5432/myapp_dev
DEBUG=true

# .env.production  
NODE_ENV=production
DATABASE_URL=postgresql://prod-host:5432/myapp
DEBUG=false

Best Practices

1. Validate early: Call createEnv() at app startup
2. Fail fast: Let validation errors crash the app on startup
3. Feature flags: Use for gradual rollouts and A/B testing
4. Environment separation: Different configs per environment
5. Type safety: Let TypeScript catch config errors

API Reference

Functions

• defineConfig(config) - Define application configuration
• createEnv(schema) - Validate environment variables with Zod
• featureFlag(name, default?, environments?) - Get feature flag value
• setFeatureFlag(config) - Set feature flag configuration
• getConfig(key) - Get configuration value by key
• getAllConfig() - Get all configuration
• resetConfig() - Reset all configuration (testing)

Types

• ConfigOptions - Base configuration interface
• FeatureFlagConfig - Feature flag configuration