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.
• Reference environment variables from inside your config files with slots, including chains, fallbacks and self-references.
• Override anything at runtime with environment variables — no rebuild required.
• Ship a separate, browser-safe client configuration derived from the same schema.

How It Works

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

1. File-based – Define your configuration files.
2. 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,
  EnvironmentVariableSource,
  FileSource,
} from "@layerfig/config";

export const config = new ConfigBuilder({
  validate: (finalConfig, z) =>
    z
      .object({
        baseURL: z.url(),
      })
      .parse(finalConfig),
})
  //  1. Starts with a base configuration.
  .addSource(new FileSource("base.json"))
  // 2. Merges with the previous source if needed
  // .addSource(new FileSource("live.json"))
  // 3. Allows environment variables
  //    to override previous values (optional).
  .addSource(new EnvironmentVariableSource())
  // 4. Validates the merged configuration and
  //    returns the final, type-safe object.
  .build();

Related

• config-rs
• zod-config