go-envconfig

The overwrite tag modifies how default values are applied based on the initial state of the struct field:

1. If the field has a zero value:

   • No env var: Field gets the default value.
   • Env var present: Field gets the env var value.

2. If the field has a non-zero value:

   • No env var: Field keeps its existing value (the default is ignored).
   • Env var present: Field is overwritten with the env var value.

To populate a struct from environment variables, define a struct with fields using the env tag and call envconfig.Process(ctx, &target). All fields intended for processing must be public. Nested structs are supported, and if a nested struct is a pointer, it will be automatically instantiated.

type MyConfig struct {
  Port     string `env:"PORT"`
  Username string `env:"USERNAME"`
}

// ... set environment variables PORT=5555 and USERNAME=yoyo ...

func main() {
  ctx := context.Background()
  var c MyConfig
  if err := envconfig.Process(ctx, &c); err != nil {
    log.Fatal(err)
  }
}

To avoid relying on global environment variables during testing (which prevents parallel testing), use envconfig.ProcessWith with a MapLookuper. This allows you to provide a static map of key-value pairs to simulate the environment.

lookuper := envconfig.MapLookuper(map[string]string{
  "FOO": "bar",
  "ZIP": "zap",
})

var config Config
err := envconfig.ProcessWith(ctx, &envconfig.Config{
  Target:   &config,
  Lookuper: lookuper,
})

MustProcess is a helper that calls Process and panics if an error occurs. It returns the populated struct, making it useful for anonymous initializations in scripts or CLIs where graceful error handling is not a priority.

Note: This is not recommended for production services due to the panic behavior.

var env = envconfig.MustProcess(context.Background(), &struct{
  Field string `env:"FIELD,required"`
})

A Lookuper provides the mechanism for finding environment variable values. You can use different implementations depending on your needs:

• OsLookuper(): Uses os.LookupEnv (default).
• MapLookuper(map[string]string): Uses a provided map. Ideal for testing to avoid mutating the global environment.
• PrefixLookuper(prefix string, l Lookuper): Prepends a prefix to all keys looked up by the underlying lookuper.
• MultiLookuper(lookupers ...Lookuper): Searches through a list of lookupers in the order provided.

For advanced control, use ProcessWith by providing a Config struct. This allows you to customize the Lookuper, default delimiters, separators, and other behaviors.

Process can also accept a *Config as its target to use that configuration for the decoding process.

Use Process to decode environment variables into a struct. Struct fields must be tagged with env:"KEY" to specify the environment variable name. The key is case-sensitive.

Supported types include all built-in types except Func and Chan. If a field is a pointer, envconfig will automatically initialize it.

type MyStruct struct {
  A string `env:"A"` // resolves A to $A
  B string `env:"B,required"` // resolves B to $B, errors if $B is unset
  C string `env:"C,default=foo"` // resolves C to $C, defaults to "foo"
}

var cfg MyStruct
err := envconfig.Process(ctx, &cfg)

The LegacyMutatorFunc helper is deprecated. It was used to wrap older mutator functions that only provided the key and value. While it can still be used to ease transitions, it is inherently lossy because it cannot access the resolvedKey or originalValue provided by the new Mutator interface.

Recommendation: Use MutatorFunc instead to take full advantage of the available context.

// Deprecated: Use [MutatorFunc] instead.
func LegacyMutatorFunc(fn func(ctx context.Context, key, value string) (string, error)) MutatorFunc