https://github.com/kaatinga/settings
The package looks up necessary environment variables and use them to specify settings for your application.
https://github.com/kaatinga/settings
config configuration environment-variables go golang help-wanted needs-review needs-rework needs-tests reflection settings-management
Last synced: 5 months ago
JSON representation
The package looks up necessary environment variables and use them to specify settings for your application.
- Host: GitHub
- URL: https://github.com/kaatinga/settings
- Owner: kaatinga
- License: mit
- Created: 2020-10-08T12:22:35.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-12-25T21:58:32.000Z (6 months ago)
- Last Synced: 2025-12-27T08:22:22.737Z (6 months ago)
- Topics: config, configuration, environment-variables, go, golang, help-wanted, needs-review, needs-rework, needs-tests, reflection, settings-management
- Language: Go
- Homepage:
- Size: 134 KB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://github.com/kaatinga/settings/releases)
[](https://github.com/kaatinga/settings/blob/main/LICENSE)
[](https://codecov.io/gh/kaatinga/settings)
[](https://github.com/kaatinga/settings/actions/workflows/golang_ci.yml)
[](https://github.com/kaatinga/settings/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
[](https://github.com/kaatinga/settings/actions/workflows/github-code-scanning/codeql)
# settings
`settings` is a Go package that simplifies configuration management for your application. It automatically loads environment variables into your configuration structs, supports default values, and validates fields using standard `validate` tags. With `settings`, you can define your application's configuration in a type-safe, declarative way—eliminating boilerplate code and reducing the risk of misconfiguration.
## Contents
1. [Installation](#1-installation)
2. [Description](#2-description)
3. [Limitations](#3-limitations)
## 1. Installation
Use `go get` to install the package:
```bash
go get github.com/kaatinga/settings
````
Then, import the package into your own code:
```go
import "github.com/kaatinga/settings"
```
## 2. Description
### How to use
Create a settings model where you can use tags `env`, `default` and `validate`. Announce a variable and call `Load()`:
```go
type Settings struct {
Port string `env:"PORT" validate:"numeric"`
Database string `env:"DATABASE"`
CacheSize byte `env:"CACHE_SIZE" default:"50"`
LaunchMode string `env:"LAUNCH_MODE"`
}
var settings Settings
err := Load(&settings)
if err != nil {
return err
}
```
The `env` tag must contain the name of the related environment variable.
The `default` tag contains a default value that is used in case the environment variable was not found.
The `validate` tag may contain an optional validation rule fallowing the documentation of the [validator package](https://github.com/go-playground/validator/).
### Supported types
| Type | Real type |
|----------------|----------------|
| string | - |
| boolean | - |
| ~int | - |
| ~uint | - |
| time.Duration | int64 |
| []string | []string |
| []byte | []byte |
### Nested structs
Nested structs can be added via pointer or without pointer. Example:
```go
type Model2 struct {
CacheSize byte `env:"CACHE_SIZE"`
}
type Model3 struct {
Port string `env:"PORT validate:"numeric"`
}
type Model1 struct {
Database string `env:"DATABASE"`
Model2 *Model2
Model3 Model3
}
```
The nested structs that added via pointer must not be necessarily initialized:
```go
var settings Model1
if err := Load(&settings); err != nil {
return err
}
```
Nonetheless, if you want, you can do it.
```go
var settings = Model1{Model2: new(Model2)}
if err := Load(&settings); err != nil {
return err
}
```
## 3. Limitations
The configuration model has some limitations in how it is arranged and used.
### Empty structs are not allowed
If you add an empty struct to your configuration model, `Load()` returns error.
### Load() accepts only pointer to your configuration model
The root model must be initialized and added to the `Load()` signature via pointer:
```go
err := Load(&EnvironmentSettings)
if err != nil {
return err
}
```
Otherwise, the function returns error.