Proposal: Add a new package `@valibot/config-loader`

[ysknsid25]

Motivation

The Valibot website already lists "Config files" as one of the recommended use cases in the use cases guide:

Library authors can also make use of Valibot, for example, to match configuration files with a schema and, in the event of an error, provide clear indications of the cause and how to fix the problem.

However, there is currently no official tooling for this. Every project ends up writing the same small wrapper:

import * as v from 'valibot';
import { parse as parseYaml } from 'yaml';
import { readFileSync } from 'node:fs';

function loadAppConfig() {
  const raw = readFileSync('app.config.yaml', 'utf8');
  const parsed = parseYaml(raw);
  return v.parse(AppConfigSchema, parsed);
}

Multiplied across formats (JSON / YAML / TOML / TS), discovery rules (multiple locations, env-specific overlays), and defaults merging, this becomes meaningful boilerplate.

Existing solutions:

• cosmiconfig solves file discovery but leaves type inference entirely manual.
• c12 solves it for the unjs ecosystem but pulls in unjs-specific dependencies (confbox, defu, etc.) and is not aware of Valibot.

Proposal

Add a new package @valibot/config-loader to this monorepo (alongside @valibot/to-json-schema and @valibot/i18n), exposing a single primary API:

import * as v from 'valibot';
import { loadConfig } from '@valibot/config-loader';
import { parse as parseYaml } from 'yaml';

const ConfigSchema = v.object({
  port: v.pipe(v.number(), v.integer()),
  database: v.object({ url: v.pipe(v.string(), v.url()) }),
});

const config = await loadConfig({
  schema: ConfigSchema,
  name: 'myapp',
  envName: process.env.NODE_ENV,
  parsers: { '.yaml': parseYaml, '.yml': parseYaml },
  defaults: { port: 3000 },
});
// config is typed as v.InferOutput<typeof ConfigSchema>

Design principles

1. Zero runtime dependencies in the core. JSON / JS / MJS / CJS are handled with Node built-ins (JSON.parse, dynamic import()).
2. Bring-your-own parser for YAML / TOML / INI / JSON5. Users pass parsers: { '.yaml': fn }. This avoids coupling Valibot to any third-party parser library or external ecosystem.
3. Automatic TypeScript inference from the schema — no manual v.parse call.
4. Pluggable merge strategy. Default is a shallow merge (zero deps). Users who want deep merge can pass merge: defu or merge: lodash.merge.
5. jiti as an optional peerDependency for .ts config files (users who don't need it pay nothing).
6. Mirrors the existing pattern of @valibot/to-json-schema: only peerDependencies on valibot itself.

Scope (v1)

• loadConfig (async only)
• File discovery (configurable cwd, multiple extensions)
• Environment overlays (myapp.config.{envName}.{ext})
• Schema validation with full type inference
• defaults with pluggable merge option (shallow by default)
• Built-in .json / .js / .mjs / .cjs handling
• BYO parser API for everything else

Out of scope (v1)

• Sync API (deferred — ESM dynamic import is async by spec)
• extends / layered config
• File watching
• Bundled YAML/TOML parsers (kept BYO to preserve zero-dep)
• Writing config files

Alternatives considered

1. cosmiconfig + valibot — works but every project rewrites the wrapper, and type inference is manual.
2. c12 + valibot — works but pulls in confbox, defu, and the broader unjs stack as hard dependencies.
3. Website guide only — documenting the wrapper pattern does not remove the boilerplate.
4. Community package — possible, but config loading is common enough to justify an official primitive like @valibot/to-json-schema.

Naming

Proposed: @valibot/config-loader. Alternatives: @valibot/from-config, @valibot/load-config.

Prior art / context

• No existing issue, PR, or discussion proposes this.
• Discussion #1393 (CLI Builder) covers CLI argument parsing — a different domain.
• The use case is already officially endorsed in the use cases guide.

PoC

I've created a draft, and I'd like to discuss it based on that.

[fabian-hiller]

I like the idea! Should be rename envName into mode? Would you be interested in maintaining this package?

[yslpn]

Hi @ysknsid25 Thank you for your participation in the Valibot ecosystem.

I can't recommend cosmiconfig because it has a lot of dependencies. For example, the e18e community (https://e18e.dev/docs/replacements/cosmiconfig.html) considers it bad for the nodejs ecosystem. It seems this is due to the dependency that adds yaml support and takes up 370 KB (https://node-modules.dev/grid/depth#install=cosmiconfig). Not all projects need yaml support.

Perhaps we should create some kind of abstraction that allows the user to choose between cosmiconfig and lilconfig. But then @valibot/config-loader loses its overall value for the user, as it adds very little.

[ysknsid25]

Thank you for the comment. Three clarifications, since the concerns above are based on a different design than this PR.

1. No discovery-library dependency

@valibot/config-loader has no runtime dependencies on cosmiconfig, lilconfig, or any other discovery library. The e18e dependency-graph concern around cosmiconfig is not applicable here.

2. Parsers are bring-your-own

The package never bundles YAML / TOML / JSON5 / etc. The core only handles .json / .js / .mjs / .cjs via Node built-ins, and parsers: { '.yaml': fn } lets the user opt into any extension on top.

3. Benefits to the user

The Valibot use cases guide already endorses config validation as a use case, but no official primitive supports it today. This PR fills that gap.

The value is not "we ship a parser" — it's removing the wrapper code that every Valibot user currently writes to load and validate their config:

// now, every project rewrites this
import { readFile } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import * as v from 'valibot';
import { parse as parseYaml } from 'yaml';

async function load() {
  const base = existsSync('app.config.yaml')
    ? parseYaml(await readFile('app.config.yaml', 'utf8'))
    : {};
  const env = process.env.NODE_ENV;
  const overlay = env && existsSync(`app.config.${env}.yaml`)
    ? parseYaml(await readFile(`app.config.${env}.yaml`, 'utf8'))
    : {};
  return v.parseAsync(Schema, { port: 3000, ...base, ...overlay });
}

if @valibot/config-loader will be released...

import { loadConfig } from '@valibot/config-loader';

const config = await loadConfig({
  schema: Schema,
  name: ['app.config', `app.config.${process.env.NODE_ENV}`],
  parsers: { '.yaml': parseYaml },
  defaults: { port: 3000 },
});

It could be even shorter if using formats like JSON.

import { loadConfig } from '@valibot/config-loader';

const config = await loadConfig({
  schema: Schema,
  name: ['app.config', `app.config.${process.env.NODE_ENV}`],
});

Beyond removing the boilerplate, users gain:

1. Layered merge name as an array declaratively expresses env overlays. No hand-rolled "read → exists check → merge" per layer.
2. Defaults merge defaults + merge together, shallow by default and pluggable for deep. Removes a common class of hand-rolled merge bugs.
3. File discovery for library or framework authors whose users pick the config format, multi-extension lookup (.json / .js / .mjs / .cjs + user-registered parsers) removes the hand-rolled "try each extension" code. The same primitive that supports the app-developer case above also covers the tooling case.
4. Overridable built-ins parsers: { '.json': json5Parser } swaps the native handler, so users are never locked to a specific parser per extension.

This package is also aligned with the existing pattern of @valibot/to-json-schema: a thin Valibot-side primitive, with ecosystem-specific concerns (parsers / converters) left to the user. Concretely, @valibot/to-json-schema emits a JSON Schema object and stops there — the user picks the consumer (AJV for validation, OpenAPI generators for API docs, form renderers, etc.) and the package bundles none of them.

@valibot/config-loader applies the same boundary: discovery + merge + Valibot validation on the package side, and whichever YAML / TOML / JSON5 library you prefer on the user side.

Given the above, the package is doing more than "very little" — Not only will users no longer need to regenerate the wrapper, but they may also receive four additional benefits.

[ysknsid25]

@fabian-hiller

Thank you for feedback!!

1. envName → mode

While iterating on the API I went one step further than a rename and dropped the env-overlay convention entirely. The reasoning: the rest of the design is "no baked-in conventions" (BYO parser, no .config. infix, no required extensions list), but <name>.config.<mode>.<ext> was still imposing a specific filename pattern on every user.

The current iteration lets name accept an array of base names that are loaded and merged in order:

const config = await loadConfig({
  schema: Schema,
  name: ['app.config', `app.config.${process.env.NODE_ENV}`],
  parsers: { '.yaml': parseYaml },
  defaults: { port: 3000 },
});

Benefits:

• One concept (name as an ordered layer list) instead of two (name + mode).
• Users control the naming pattern fully. no forced .config. infix or <name>.config.<mode>.<ext> shape.
• Symmetric with how parsers already drives extension discovery.
• Env overlays remain trivially expressible at the call site.

If you'd prefer keeping a mode option as sugar on top of this primitive, I can add it back, but my preference is to ship the minimal API first.

2. Maintenance

Yes! I’m very interested, and I’d love to help maintain this package.