ConfigKit loads YAML into your application's Go configuration type, combines the inputs you choose, and lets you inspect where the final values came from. You supply the types, defaults, and application rules; ConfigKit handles loading, combination, strict decoding, and inspection.

Linux is release-validated; macOS support is best-effort. See the platform support policy.

Load a configuration file

import "go.maximumdirect.net/configkit"

type Config struct {
    Enabled bool `yaml:"enabled"`
    Workers int  `yaml:"workers"`
}

func ReadConfig(path string) (Config, error) {
    result, err := configkit.Load[Config](configkit.File(path))
    if err != nil {
        return Config{}, err
    }
    return result.Config, nil
}

Existing consumers should follow the module-path migration guidance.

Add the features you need

Start with one file. Optional features use the same loading and inspection model:

Choose inputs: read files, an application-owned fs.FS, bytes, a reader, or a Go mapping. Use explicit search descriptions when the application should look in several places.
Supply lower-priority settings: use LoadLayered for bundled defaults that application configuration can override.
Combine configuration: add declared imports, select one overlay, or pass values explicitly set by your CLI parser.
Reuse settings: let one named entry inherit from a sibling. Identified lists also support record inheritance and replace, append, or upsert operations.
Apply application rules: derive or normalize values in a resolver, then check the final configuration in a validator.
Handle credentials: use environment-name references and choose which configuration fields to hide in inspection output.
Inspect a load: examine sources, presence, history, safe YAML output, or changes between two loads.

The consumer guide walks through these tasks and links to maintained examples. The configuration reference defines the exact YAML, combination, and lifecycle rules.

Design philosophy

ConfigKit favors consistent, predictable rules across applications. A load returns the final configuration and metadata that distinguish supplied values such as false and 0 from omissions. Applications keep their domain rules and runtime initialization.

Within one layer, independent contributions combine strictly: conflicting values are errors. Across layers, higher-priority settings can replace lower-priority settings, while mappings combine by key. Identified lists have their declared combination rules. See the worked combination examples for the details and exceptions.

Loading finishes before the call returns. ConfigKit then stays inactive until you call it again; inspection uses the saved result. See completion and resource lifetime.

The architecture goals and ADRs explain design decisions, including shared import and inheritance ordering. Future work lists possible extensions. Contributors can start with the development guide; release maintainers use the release procedure.

ConfigKit code is licensed under the LGPL v3.0 or later.

Open Source attribution notices are available.