WtfConfig

A hierarchical configuration management library for Node.js applications that supports YAML files, environment variables, and Zod schema validation.

Features

• Hierarchical configuration loading with environment-specific overrides
• Zod schema validation for configuration files with full type inference
• Variable replacement with configurable placeholders
• Multiple configuration sources: files, environment variables, and runtime configuration
• TypeScript support with automatic type inference from Zod schemas

Installation

npm install wtfconfig zod

Usage

import { WtfConfigContainer } from 'wtfconfig'
import { z } from 'zod'

// Define your configuration schema with Zod
const ConfigSchema = z.object({
  database: z.object({
    host: z.string(),
    port: z.number(),
    name: z.string(),
  }),
  server: z.object({
    port: z.number().default(3000),
    host: z.string().default('localhost'),
  }),
})

// Initialize with root directory and Zod schema
const configContainer = new WtfConfigContainer(
  process.cwd(),
  ConfigSchema,
  './config', // optional config directory
)

// Get configuration - type is automatically inferred from schema
const config = configContainer.getConfig()

// TypeScript knows the exact shape:
console.log(config.database.host) // string
console.log(config.server.port) // number

Configuration Loading Order

The library loads configuration files in the following priority order (later files override earlier ones):

1. default.yaml
2. default-{NODE_APP_INSTANCE}.yaml (if NODE_APP_INSTANCE is set)
3. {environment}.yaml (e.g., develop.yaml, production.yaml)
4. {environment}-{NODE_APP_INSTANCE}.yaml (if NODE_APP_INSTANCE is set)
5. local.yaml
6. local-{environment}.yaml
7. local-{NODE_APP_INSTANCE}.yaml (if NODE_APP_INSTANCE is set)
8. Environment variable NODE_CONFIG (JSON format)

Environment Variables

• NODE_ENV: Determines which environment-specific config files to load (default: 'development')
• NODE_APP_INSTANCE: Used for instance-specific configuration files
• BASE_DIR: Override the base directory for the application
• CONFIG_DIR: Override the configuration directory path
• CONFIG_RC: Path to the configuration settings file (default: .configrc)
• NODE_CONFIG: JSON configuration to merge at runtime

Configuration Settings File

Create a .configrc file in your project root to customize paths:

{
  "baseDirFromSettings": "/path/to/base",
  "configDirFromSettings": "/path/to/config"
}

Variable Replacement

Use [$basedir] in your YAML files to reference the base directory:

database:
  path: '[$basedir]/data/app.db'

Development

Setup

make install

Build

make build

Test

make test

Lint

make lint

Requirements

• Node.js >= 22

License

MIT