Key Features

Expressive Schema

Built on top of @versionzero/schema.

Configurator introspects schema structure and metadata to define configurables.

The fluent Schema API makes complex nested and variant configurations intuitive to build. The schema acts as the source of truth for structure, validation, and transformation.

The schema supports both sync and async processing, enabling lazy evaluation, dependency injection, validation of network or file system resources, transforming data through complex processing pipelines, and dynamic resolution to allow handling different data shapes based on runtime conditions.

Union schemas let you define multiple alternative schemas, and Selectors enable hierarchical command structures where choosing one option activates related configuration sections.

Out of the box, the schema handles basic types and provides a rich library of processors for parsing and validation, and can be extended with your own custom schemas and processors. Perfect for plugins, deployment targets, CLI commands, or any scenario where your config structure varies at runtime.

Composable Configuration Sources

Configurator treats configuration sources as independently defined first-class components. Each ConfigurationSource handles one concern (CLI args, env vars, JSON files, etc.) while contributing to a systematic priority resolution process. This eliminates the manual orchestration typically required when combining multiple configuration approaches, and makes extending with additional sources straightforward.

Configuration as a Data Model

The structure of the validated output configuration object is intended to mirror an "idealized" config file format for your application. If a schema hierarchy is created to align with the structure of the application and its subsystems, then each subsystem's configured properties will be nested inside a child object. This child object can then be used in isolation to safely initialize that subsystem, without extraneous data leaking in. This reduces the "dig through a random bag of whatever" output generated by many other configuration libraries.

Built for Extension and Integration

The configuration source architecture naturally accommodates additional configuration inputs as your requirements grow. Whether you need to integrate with secrets management, parameter stores, feature flag systems, or database configuration, the same priority resolution and validation pipeline applies. Custom sources participate as first-class citizens alongside the built-in CLI, environment, and file sources.

For larger applications, the schema-first approach creates clean interfaces between subsystems. Each component can define its own local configuration schema, and the validated output provides exactly the properties that subsystem needs.

(These capabilities are leveraged by Version Zero's Module Manager, a higher-level abstraction that builds on Configurator to support embedded declarative schemas, dependency injection, and lifecycle management for modular applications.)