Skip to content

knadh/koanf/v2 — v2.3.8 snapshot

Pinned: v2.3.8 Source: tagged source

Loading config

Use github.com/knadh/koanf/providers/env/v2 and github.com/go-viper/mapstructure/v2; their v1 call shapes are incompatible.

k := koanf.New(".")

// Load from environment (prefix APP_, underscore-separated keys)
envProvider := env.Provider(".", env.Opt{
    Prefix: "APP_",
    TransformFunc: func(key, value string) (string, any) {
        key = strings.TrimPrefix(key, "APP_")
        return strings.ReplaceAll(strings.ToLower(key), "_", "."), value
    },
})
if err := k.Load(envProvider, nil); err != nil {
    return fmt.Errorf("load environment: %w", err)
}

// Load from YAML file
if err := k.Load(file.Provider("config.yaml"), yaml.Parser()); err != nil {
    return fmt.Errorf("load YAML: %w", err)
}

// Load from embedded FS
embeddedProvider := fs.Provider(embeddedFS, "config.yaml")
if err := k.Load(embeddedProvider, yaml.Parser()); err != nil {
    return fmt.Errorf("load embedded YAML: %w", err)
}

Unmarshalling

var cfg MyConfig
if err := k.Unmarshal("", &cfg); err != nil {
    return err
}

// With custom decode hooks (used in golusoris core/config/)
if err := k.UnmarshalWithConf("", &cfg, koanf.UnmarshalConf{
    Tag: "koanf",
    DecoderConfig: &mapstructure.DecoderConfig{
        DecodeHook: mapstructure.ComposeDecodeHookFunc(
            mapstructure.StringToTimeDurationHookFunc(),
            mapstructure.StringToSliceHookFunc(","),
        ),
        Metadata:         nil,
        Result:           &cfg,
        WeaklyTypedInput: true,
    },
}); err != nil {
    return err
}

File-watch (hot reload)

provider := file.Provider("config.yaml")
if err := provider.Watch(func(_ any, watchErr error) {
    if watchErr != nil {
        logger.Warn("config watch failed", slog.Any("err", watchErr))
        return
    }
    if err := k.Load(provider, yaml.Parser()); err != nil {
        logger.Warn("config reload failed", slog.Any("err", err))
    }
}); err != nil {
    return fmt.Errorf("watch config: %w", err)
}
lc.Append(fx.Hook{
    OnStop: func(context.Context) error { return provider.Unwatch() },
})

Getting values

k.String("database.host")
k.Int("server.port")
k.Duration("cache.ttl")
k.Bool("feature.enabled")
k.Strings("allowed_origins")   // []string from comma-sep or YAML list

golusoris usage

  • core/config/ — Koanf instance provided as Fx singleton; environment, YAML, and file-watch support.
  • Every subpackage config struct tagged with koanf:"...".