envvar
Tiny-but-mighty environment reader and struct binder for Go.
- Zero deps, stdlib only.
- Typed getters: bool, int, float64, duration, URL, IP, slices.
- Struct binding with tags, defaults, and JSON decode.
${VAR}and${VAR:-def}expansion.- Pluggable sources (env + maps + composites).
- Lazy getters and safe redacted dumps.
- Optional hooks for metrics/tracing without adding deps.
Install
go get github.com/aatuh/envvar/v2
Quick start
Check the examples from the examples package.
Run examples with:
go test -v -count 1 ./examples
# Run specific example.
go test -v -count 1 ./examples -run TestBasicGetters
# Run specific example.
go test -v -count 1 ./examples -run TestBasicGetters
Features
Typed getters
Get,GetOr,MustGetGetBool,GetInt,GetFloat64,GetDurationGetURL,GetIP,GetStringSlice(+GetStringSliceSep)- Generic:
GetTyped[T](key, conv) - All have
Must*andOrvariants where it makes sense.
Expansion
${NAME}and${NAME:-default}are expanded in values read from env and when usingExpandMap.
Lazy getters
Cache-on-first-use helpers, e.g. LazyBool("DEBUG")().
Struct binding
Populate a struct from environment with tags:
env:"NAME[,required]"choose the env var name and requiredness.envdef:"value"default used if missing.envsep:","separator for[]string(default ",").envjson:"true"JSON decode into field type (maps, slices, structs).
Pointer fields are allocated automatically.
Prefix binding
Try a prefixed variable first, then fall back to the base name:
// Tries MYAPP_PORT first, then PORT.
envvar.MustBindWithPrefix(&cfg, "MYAPP_")
envvar.MustBindWithPrefix(&cfg, "MYAPP_")
Environment variable sources
By default, getters and Bind read from process environment variables.
You can also load from files using LoadEnvVars:
// Load from specific files
if err := envvar.LoadEnvVars([]string{"./.env.local", "./.env"}); err != nil {
// handle error
}
// Or use the default paths (.env, then /env/.env)
envvar.MustLoadEnvVars(nil)
port := envvar.MustGetInt("PORT") // reads from loaded env vars
if err := envvar.LoadEnvVars([]string{"./.env.local", "./.env"}); err != nil {
// handle error
}
// Or use the default paths (.env, then /env/.env)
envvar.MustLoadEnvVars(nil)
port := envvar.MustGetInt("PORT") // reads from loaded env vars
Map expansion helper
Expand ${VAR} and ${VAR:-def} inside a map, using map values first,
then process environment variables:
in := map[string]string{
"HOST": "db.local",
"DSN": "postgres://${HOST}:${PORT:-5432}/app",
}
out := envvar.MustExpandMap(in)
// out["DSN"] == "postgres://db.local:5432/app"
"HOST": "db.local",
"DSN": "postgres://${HOST}:${PORT:-5432}/app",
}
out := envvar.MustExpandMap(in)
// out["DSN"] == "postgres://db.local:5432/app"
.env loading
// Try custom locations in order:
if err := envvar.LoadEnvVars([]string{"./.env.local", "./.env"}); err != nil {
// handle error
}
if err := envvar.LoadEnvVars([]string{"./.env.local", "./.env"}); err != nil {
// handle error
}
Redacted dump
log.Printf("env: %#v", envvar.DumpRedacted())
Heuristics redact keys containing SECRET, TOKEN, PASSWORD, or
suffix _KEY.
Error handling
- All binding errors are aggregated and returned as a
MultiError. - Missing required fields are reported clearly.
Observability hooks (optional)
type myHook struct{}
func (myHook) OnLoad(src string, keys int) {}
func (myHook) OnGet(k string, ok bool, err error, d time.Duration) {}
envvar.SetHook(myHook{})
func (myHook) OnLoad(src string, keys int) {}
func (myHook) OnGet(k string, ok bool, err error, d time.Duration) {}
envvar.SetHook(myHook{})