Layerfig

Skip to content

Type-safe layered configuration. Merge files and environment variables, validate with any schema, and get a runtime-checked object with full TypeScript IntelliSense.

Features

Define declarative, isolated, and per-environment configuration files (.json, or other file extensions via parsers).
Validate your configuration with zod, or bring your preferred schema validation library.
Use a type-safe and runtime-checked configuration object across your app.

How It Works

When using ConfigBuilder, configuration is loaded from two primary sources:

File-based – Define your configuration files.
Environment variables – Override configurations dynamically. This is useful for pre-built containers that require specific values at runtime.

Since the configuration follows a cascading approach, the final result depends on the order in which sources are added.

import { ConfigBuilder } from "@layerfig/config";

export const config = new ConfigBuilder({
  validate: (finalConfig, z) => {
    const schema = z.object({
      baseURL: z.url()
    })

    return schema.parse(finalConfig)
  },
})
  // 1. Starts with a base configuration.
  .addSource("base.json")
  // 2. Merges with the previous source.
  .addSource("live.json")
  // 3. Allows environment variables to override previous values (optional).
  .addSource(ConfigBuilder.createEnvVarSource())
  // 4. Validates the merged configuration and returns the final, type-safe object.
  .build();