define-config pages
- define-config
- define-config
define-config
A TypeScript library for config written as code, merged across layers and checked with any Standard Schema validator.
define-config is a small TypeScript library for a tool's configuration. A config file holds a list of entries. The library merges the entries of every layer, such as a user's folder and then a project's, checks the result against your schema, and tells you which entry set each key.
Status
Version 0.5.0 is on npm under the Apache-2.0 licence. It has no runtime dependencies, and it runs under Bun or Node.js. A config file written in TypeScript loads under Bun; under Node.js 22.14 it does not, while .mjs, .js and .json config files do. The examples on these pages run under Bun. [verify: the Node.js floor. 0.5.0 declares none; the repository's unpublished 0.5.2 declares Node.js 22 or later.]
define-config is pre-1.0. Names and behaviour can still change between minor versions, and the changelog says what changed in each one.
How a config is read
A layer is one place a config file can sit, with a label. The loader looks in each layer's folder, reads the first file it finds there, and merges every entry in layer order, so a later layer wins.
Nothing is thrown at you for a bad value. Every problem comes back as a diagnostic, an object with a level, a stable code and the key path it is about, and your tool decides what to do with it.
Who it is for
Each step of the range adds one need, and each page answers one of them.
| Step | Your situation | Page |
|---|---|---|
| One project | You write a tool and want its users to configure it in a typed file, with a per-user file under it | Getting started |
| A team | A shared layer sets defaults, and each project removes or replaces parts of it | Layers and merge rules |
| A tool that runs steps | Users write flows of steps, and your tool checks every outcome and loop before it runs anything | Step graphs |
| An organisation | One host tool reads the same layers for every project, and you need to know where each value came from | Getting started, where provenance is read |
How it connects to rafa
rafa reads its own configuration through define-config. Since rafa 0.46.0, a project's rafa.config.ts (or rafa.config.mjs) is a list of entries. In 0.46.0 a .rafa/config.yaml beside that file is not read, and rafa warns about it. Since 0.47.0 the YAML file is read over the module file, key by key. Both versions pin define-config 0.5.0.
ned, the planned notification library, uses define-config for its ned.config.ts in its design.