Meldkit

Typed YAML configuration for Node.js, with recursive includes, predictable merging, required environment placeholders, and caller-owned runtime validation.

Meldkit owns configuration composition. Your application owns the schema and the decision about which values are secrets.

Install

npm install meldkit

Meldkit is an ESM-only library for Node.js 24 and newer. It includes and re-exports Zod for the recommended runtime-validation boundary, while loadConfig also accepts any synchronous object with a compatible parse(value) method.

Quick start

Commit non-secret defaults in YAML:

# config/base.yaml
server:
  host: "127.0.0.1"
  port: 4000
log:
  level: "info"
database:
  host: "database.example.test"
  password: "${DATABASE_PASSWORD}"

Override only the local differences:

# config/local.yaml
include: "./base.yaml"
log:
  level: "debug"

Define and load the typed contract:

import { loadConfig, z } from "meldkit";

const ConfigSchema = z.object({
  server: z.object({
    host: z.string().min(1),
    port: z.number().int().positive(),
  }),
  log: z.object({
    level: z.enum(["debug", "info", "warn", "error"]),
  }),
  database: z.object({
    host: z.string().min(1),
    password: z.string().min(1),
  }),
});

export const config = loadConfig({
  path: "./config/local.yaml",
  schema: ConfigSchema,
});

The result is inferred from the schema. Meldkit reads configuration synchronously at startup and never mutates process.env. When env is omitted, Meldkit snapshots process.env automatically.

In-memory YAML

Use loadConfigText when YAML already comes from a caller-owned source, such as a test fixture or migration tool:

import { loadConfigText, z } from "meldkit";

const config = loadConfigText({
  env: { DATABASE_PASSWORD: "fixture-value" },
  schema: z.object({
    database: z.object({
      host: z.string().min(1),
      password: z.string().min(1),
    }),
  }),
  text: `
    database:
      host: database.example.test
      password: "\${DATABASE_PASSWORD}"
  `,
});

The text loader parses one document and does not access the filesystem. A root-level include fails; use loadConfig with a path when configuration inherits another file.

Includes and merging

include is allowed only at the YAML document root and points to one file relative to the file containing it. Includes may be recursive.

• The included document is the base.
• The including document is the override.
• Plain objects merge recursively.
• Arrays, scalars, and null replace the base value.
• Include cycles fail before validation.

Documents merge before environment placeholders resolve. An override can therefore replace a base branch containing placeholders that are no longer relevant.

Environment ownership

Meldkit never discovers or parses .env* files. Populate the process environment before starting the application with the tool that owns your secret workflow:

dotenvx run -f .env.local -- node dist/main.js
node --env-file=.env.local dist/main.js

See the official dotenvx -f documentation and Node.js --env-file documentation for their precedence rules.

GitVaulty can materialize a protected environment file before either command. Containers, CI, and production platforms should inject variables through their runtime secret boundary.

If env is omitted, Meldkit takes a snapshot of process.env at load time. Passing env supplies the complete environment map instead, which keeps tests and runtime adapters deterministic:

const config = loadConfig({
  env: { DATABASE_PASSWORD: "fixture-value" },
  path: "./config/local.yaml",
  schema: ConfigSchema,
});

Environment-file naming and precedence belong to the launcher, not Meldkit.

Environment placeholders

Use ${UPPER_SNAKE_CASE} in YAML string values. Missing and empty values fail with the variable name and configuration path, never the resolved value.

Optional placeholders such as ${?TOKEN} are intentionally unsupported. If a setting is optional, omit the YAML field and express optionality or a default in the schema:

const ConfigSchema = z.object({
  webhookSecret: z.string().min(1).optional(),
});

This keeps absence distinct from an empty string and prevents deployment mistakes from silently becoming valid configuration.

More documentation

• Configuration semantics
• API reference

License

MIT