Viper — Complete Configuration Solution for Go

What it is

Viper is the most widely adopted configuration library for Go applications. It supports reading configuration from JSON, TOML, YAML, HCL, envfile, and Java properties formats. Viper also reads from environment variables, command-line flags, remote config systems (etcd, Consul), and provides live watching for config file changes.

Viper is used by Go developers building applications that need flexible configuration management across multiple environments (development, staging, production) without hardcoding values.

How it saves time or tokens

Viper eliminates the need to write custom config parsing code for each format. Setting defaults, overriding with environment variables, and binding CLI flags all work through a single API. The live-watching feature reloads config files without restarting the application, which is valuable for long-running services. Viper handles config merging across multiple sources with a clear precedence order.

How to use

1. Install Viper with go get github.com/spf13/viper.
2. Set config file name, path, and type, then call viper.ReadInConfig() to load.
3. Access values with viper.GetString(), viper.GetInt(), and other typed getters.

Example

package main

import (
    "fmt"
    "github.com/spf13/viper"
)

func main() {
    viper.SetConfigName("config")
    viper.SetConfigType("yaml")
    viper.AddConfigPath(".")
    viper.SetDefault("port", 8080)

    if err := viper.ReadInConfig(); err != nil {
        fmt.Printf("No config file found: %v\n", err)
    }

    viper.AutomaticEnv()
    port := viper.GetInt("port")
    fmt.Printf("Server starting on port %d\n", port)
}

Related on TokRepo

• AI tools for coding -- developer libraries and tools
• Automation tools -- configuration and automation workflows

Common pitfalls

• Viper uses a global singleton by default; for library code or multiple configs, create isolated instances with viper.New().
• Environment variable binding is case-insensitive and uses underscores for nested keys (e.g., DATABASE_HOST maps to database.host), which can cause unexpected collisions.
• The WatchConfig feature requires fsnotify and may not work reliably on all filesystems, particularly network-mounted volumes.