@meltstudio/config-loader

A type-safe configuration loader for Node.js. Define your schema once, load from YAML, JSON, or TOML files, .env files, environment variables, and CLI arguments — and get a fully typed result with zero manual type annotations.

Upgrading from v1? v1.x is deprecated and no longer maintained. Install the latest version with npm install @meltstudio/config-loader@latest.

Full documentation

Why config-loader?

Most config libraries give you Record<string, unknown> and leave you to cast or validate manually. config-loader infers TypeScript types directly from your schema definition:

import c from "@meltstudio/config-loader";

const config = c
  .schema({
    port: c.number({ required: true, env: "PORT" }),
    host: c.string({ env: "HOST", defaultValue: "localhost" }),
    env: c.string({
      env: "NODE_ENV",
      defaultValue: "development",
      oneOf: ["development", "staging", "production"],
    }),
    apiKey: c.string({ env: "API_KEY", sensitive: true }),
    database: c.object({
      item: {
        host: c.string({ required: true }),
        password: c.string({ env: "DB_PASSWORD", sensitive: true }),
      },
    }),
  })
  .load({
    env: true,
    args: true,
    files: "./config.yaml",
    envFile: "./.env",
  });

// config is fully typed — no `as` casts, no separate interfaces

Features

• Full type inference — schema definition produces typed output automatically
• Multiple sources — YAML, JSON, TOML files, .env files, environment variables, CLI arguments
• Priority resolution — CLI > process.env > .env files > Config files > Defaults
• .env file support — load environment variables from .env files with automatic line tracking
• Nested objects and arrays — deeply nested configs with full type safety
• Structured errors — typed ConfigLoadError with per-field error details and warnings
• Enum constraints — restrict values to a fixed set with oneOf, with full type narrowing
• Sensitive fields — mark fields with sensitive: true to auto-mask in printConfig() and maskSecrets()
• Schema validation — optional per-field validation via Standard Schema (Zod, Valibot, ArkType, or custom)
• Strict mode — promote warnings to errors for production safety
• Default values — static or computed (via functions)
• Multiple files / directory loading — load from a list of files or an entire directory
• File watching — watch() reloads config on file changes with debouncing, change detection, and error recovery

Installation

npm install @meltstudio/config-loader

pnpm add @meltstudio/config-loader

yarn add @meltstudio/config-loader

Requires Node.js >= 20.

Watch Mode

Automatically reload config when files change. Watchers use .unref() so they don't prevent the process from exiting.

const watcher = c
  .schema({
    port: c.number({ env: "PORT", defaultValue: 3000 }),
    host: c.string({ defaultValue: "localhost" }),
  })
  .watch(
    { env: true, args: false, files: "./config.yaml" },
    {
      onChange: (newConfig, oldConfig, changes) => {
        for (const change of changes) {
          console.log(
            `${change.path}: ${String(change.oldValue)} → ${String(change.newValue)}`,
          );
        }
      },
      onError: (err) => console.error("Reload failed:", err.message),
    },
  );

// Access current config anytime
console.log(watcher.config.port);

// Stop watching
watcher.close();

Documentation

See the full documentation for:

• Schema API — primitives, objects, arrays, oneOf, sensitive, validation
• Loading & Sources — load(), loadExtended(), watch(), file/env/CLI/.env sources, printConfig(), maskSecrets(), error handling, strict mode
• TypeScript Utilities — SchemaValue, exported types, type narrowing

Examples

The example/ directory contains runnable examples:

• Basic — Schema definition, YAML file loading, nested objects and arrays, CLI arguments
• Advanced — TOML config, .env files, oneOf constraints, sensitive fields, validation, printConfig(), maskSecrets(), error handling

pnpm example:basic
pnpm example:advanced

Documentation for AI Agents

This project provides machine-readable documentation for AI coding agents at the docs site:

• llms.txt — structured index of documentation pages
• llms-full.txt — full documentation in a single Markdown file

These files follow the llms.txt standard and are generated automatically at build time. They are designed to be consumed by AI tools like Claude Code, Cursor, GitHub Copilot, and other LLM-based development assistants.

License

Built by Melt Studio. Licensed under the MIT License.