config

Documentation

Overview

Package config loads application configuration from environment variables, .env files, and JSON config files into typed Go structs.

It uses struct tags to map fields to environment variables and supports default values, type coercion, and validation via the request package's existing tag validators.

Quick Start

type AppConfig struct {
    Host     string `env:"HOST"      default:"localhost"  validate:"required"`
    Port     int    `env:"PORT"      default:"8080"       validate:"required,min=1,max=65535"`
    Debug    bool   `env:"DEBUG"     default:"false"`
    DBUrl    string `env:"DB_URL"    validate:"required,url"`
    LogLevel string `env:"LOG_LEVEL" default:"info"       validate:"oneof=debug info warn error"`
}

var cfg AppConfig
if err := config.Load(&cfg); err != nil {
    log.Fatal(err)
}

Struct Tags

• env:"VAR_NAME" — maps the field to the named environment variable
• default:"value" — fallback if env var and config file both miss
• validate:"..." — reuses request package validators (required, min, max, url, etc.)

Source Priority (high to low)

1. Environment variables (always win)
2. .env file (loaded into process env, doesn't override existing)
3. JSON config file (base config layer)
4. default:"..." tags (fallback)

Options

config.Load(&cfg,
    config.WithPrefix("APP"),           // APP_PORT instead of PORT
    config.WithEnvFile(".env"),          // Load .env file
    config.WithJSONFile("config.json"), // Load JSON config as base
    config.WithRequired(),              // Error if files don't exist
)

Supported Types

• string, bool, int/int8/16/32/64, uint variants, float32/64
• time.Duration (parses "5s", "1m30s")
• []string, []int (comma-separated: "a,b,c")
• Nested structs (flattened env: DB_HOST for field DB.Host)

Nested Structs

type Config struct {
    DB struct {
        Host string `env:"HOST" default:"localhost"`
        Port int    `env:"PORT" default:"5432"`
    }
}

// With prefix "APP": reads APP_DB_HOST, APP_DB_PORT
config.Load(&cfg, config.WithPrefix("APP"))

MustLoad

For use in main() or init(), MustLoad panics on error:

var cfg AppConfig
config.MustLoad(&cfg, config.WithEnvFile(".env"))

Index

• func Load(dst any, opts ...Option) error
• func MustLoad(dst any, opts ...Option)
• type Option
  • func WithEnvFile(path string) Option
  • func WithJSONFile(path string) Option
  • func WithPrefix(prefix string) Option
  • func WithRequired() Option

Functions

func Load

func Load(dst any, opts ...Option) error

Load populates dst from environment variables, optional .env files, and optional JSON config files, then validates the result using struct tags.

dst must be a non-nil pointer to a struct.

Sources are applied in priority order (high to low):

1. Environment variables
2. .env file values (do not override existing env vars)
3. JSON file values
4. default:"..." struct tags

func MustLoad

func MustLoad(dst any, opts ...Option)

MustLoad calls Load and panics if an error occurs. It is intended for use in main() or init() functions.

Types

type Option

type Option func(*options)

Option configures the behavior of Load.

func WithEnvFile

func WithEnvFile(path string) Option

WithEnvFile loads environment variables from a file (e.g., ".env"). Values from the file do not override existing environment variables.

func WithJSONFile

func WithJSONFile(path string) Option

WithJSONFile loads configuration from a JSON file as the base layer. Environment variables and .env values take precedence over JSON values.

func WithPrefix

func WithPrefix(prefix string) Option

WithPrefix sets a prefix for all environment variable lookups. For example, WithPrefix("APP") causes field with env:"PORT" to read APP_PORT.

func WithRequired

func WithRequired() Option

WithRequired causes Load to return an error if any specified files (env file or JSON file) do not exist.