cfg

README

English | Русский

cfg

A universal YAML configuration loader for Go applications with support for default values, environment variables (including values from .env files), and validation of required fields.

The package is not tied to any specific application — you define the configuration schema (structure) yourself in your own project. cfg is responsible only for the loading mechanism.

Installation

go get github.com/meesooqa/go-cfg

Usage

package main

import (
	"log"

	"github.com/meesooqa/go-cfg"
)

type Config struct {
	Server struct {
		Host string `yaml:"host" default:"0.0.0.0"`
		Port int    `yaml:"port" default:"8080" env:"SERVER_PORT"`
	} `yaml:"server"`

	Database struct {
		DSN string `yaml:"dsn" env:"DATABASE_DSN" required:"true"`
	} `yaml:"database"`
}

func main() {
	config, err := cfg.Load[Config]("config.yml", ".env")
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("%s:%d", config.Server.Host, config.Server.Port)
}

Struct Tags

Тег	Назначение
yaml	Field name in the YAML file
default	Value used if the field is not specified in YAML
env	Environment variable name overriding the value
required	"true" — loading fails if the field remains empty

Value Priority

environment variable (or .env) > YAML > default

Development

go test ./...       # run tests
go doc -all .       # view documentation

Project Structure

cfg.go          — entry point, Load[T] function
field.go        — string → field type conversion using reflect
defaults.go     — applying the default tag
env.go          — applying the env tag and loading .env files
required.go     — validating the required tag
*_test.go       — unit tests
example_test.go — usage examples (visible in godoc)
testdata/       — auxiliary test files

Documentation

Overview

Package cfg provides a generic configuration loader for Go applications. Settings are loaded from a YAML file, supplemented with default values (the `default` tag), overridden by environment variables (the `env` tag, optionally loaded from .env files), and validated for required fields (the `required:"true"` tag).

The package does not define any application-specific structures— the configuration schema (type T) is defined by the application that uses cfg.

Index

• func Load[T any](path string, envFiles ...string) (*T, error)

Functions

func Load

func Load[T any](path string, envFiles ...string) (*T, error)

Load reads the YAML file at the specified path and any optional .env files, parses them into a value of type T, applies default values and environment variables, and then validates required fields.

Value source precedence: env > YAML > default.

envFiles is an optional list of paths to .env files. If a file does not exist, it is silently skipped. Actual process environment variables always take precedence over values loaded from .env files.