@baseworks/config

A lightweight layered config loader for CLI tools and services. One call gives you config that merges a project-local file over a global one, in TOML (default), YAML, or JSON — the format is chosen per file by extension, so a project can override a global YAML with a local TOML.

~/.myapp/config.toml   (global)   ─┐
                                    ├─ deep-merge (local wins) ─▶ typed config
./.myapp/config.toml   (local)    ─┘

Quick start

import { createConfigManager } from '@baseworks/config'

interface AppConfig { db: string; tenants: string[] }

const cfg = createConfigManager<AppConfig>(
  'myapp',
  { db: 'file:./local.db', tenants: ['acme'] },   // defaults
  { format: 'toml', layered: true },
)

const { db, tenants } = cfg.load()   // defaults ← global ← local, deep-merged
cfg.patch({ db: 'libsql://…' })      // merge + persist to the active file

Where files live

| | path | |---|---| | global | ~/.{appName}/config.{ext} | | project-local | ./.{appName}/config.{ext} (cwd) |

• layered (layered: true) — both files load and deep-merge; local wins.
• single-file (default) — the first found (local, then global) wins.
• save() writes to the local file if a local dir/file exists, else the global one; an existing file keeps its own format regardless of format.

API

createConfigManager<T>(appName, defaults, options?) → ConfigManager<T>:

| member | purpose | |---|---| | load() | read config (merged in layered mode, else first found) | | save(cfg) | write to the active path | | patch(partial) | deep-merge partial values and persist | | clearLocal() | delete the project-local file | | writePath / globalPath / localPath | resolved absolute paths |

Options: format ('toml' | 'yaml' | 'json', default 'toml') · layered (default false).

Explicit-path helpers (no app-name convention):

import { loadConfigFile, writeConfigFile } from '@baseworks/config'

const c = loadConfigFile('~/.myapp/settings.yaml', { theme: 'dark' })
writeConfigFile('./out/config.toml', c)   // format inferred from the extension

deepMerge(base, override) is exported too, for merging config-shaped objects.

Formats

TOML via smol-toml, YAML via yaml, JSON built-in. The extension picks the parser; format only decides what a new file is written as.

Develop

pnpm test        # vitest
pnpm build       # tsup → dist