Keep your configuration clean. Keep your secrets safe.
Installation • Quick Start • Features • Examples • Contributing
You love YAML for configuration—it's clean, readable, and organized. But what about sensitive data like API keys, database passwords, and tokens? Hardcoding them is a security nightmare. 😱
envYaml bridges the gap between clean YAML configuration and secure environment variable management. Reference environment variables directly in your YAML files, and envYaml handles the rest!
# config.yml - Clean and secure! 🔒
database:
host: localhost
port: 5432
password: ${DB_PASSWORD} # Loaded from environment
api:
key: ${API_KEY} # Never committed to git
secret: ${API_SECRET} # Always securego get github.com/yuseferi/envyaml@latestRequirements: Go 1.25+
1. Create your YAML configuration:
# config.yml
host: localhost
port: 3606
password: ${DB_PASSWORD}2. Define your config struct:
type Config struct {
Host string `yaml:"host" env:"HOST"`
Port int `yaml:"port" env:"PORT"`
Password string `yaml:"password" env:"DB_PASSWORD,required"`
}3. Load and use:
package main
import (
"fmt"
"log"
"github.com/yuseferi/envyaml"
)
func main() {
var cfg Config
if err := envyaml.LoadConfig("config.yml", &cfg); err != nil {
log.Fatal(err)
}
fmt.Printf("Connected to %s:%d\n", cfg.Host, cfg.Port)
}| Feature | Description |
|---|---|
| 🔄 Seamless Integration | Combine YAML files with environment variables effortlessly |
| ✅ Required Variables | Mark critical env vars as required with automatic validation |
| 🏷️ Struct Tags | Use familiar yaml and env struct tags |
| 🛡️ Type Safety | Full Go type safety with automatic type conversion |
| 📦 Zero Config | Works out of the box with sensible defaults |
| 🪶 Lightweight | Minimal dependencies, maximum performance |
Mark sensitive variables as required to fail fast if they're missing:
type Config struct {
Host string `yaml:"host" env:"HOST"`
Port int `yaml:"port" env:"PORT"`
Password string `yaml:"password" env:"DB_PASSWORD,required"` // 👈 Required!
}
var cfg Config
err := envyaml.LoadConfig("config.yml", &cfg)
if err != nil {
// Error: failed to parse environment variables: env: required environment variable "DB_PASSWORD" is not set
log.Fatal(err)
}package main
import (
"fmt"
"log"
"os"
"github.com/yuseferi/envyaml"
)
type DatabaseConfig struct {
Host string `yaml:"host" env:"DB_HOST"`
Port int `yaml:"port" env:"DB_PORT"`
Username string `yaml:"username" env:"DB_USER"`
Password string `yaml:"password" env:"DB_PASSWORD,required"`
Database string `yaml:"database" env:"DB_NAME"`
}
type Config struct {
Database DatabaseConfig `yaml:"database"`
Debug bool `yaml:"debug" env:"DEBUG"`
}
func main() {
// Set environment variables (in production, these come from your environment)
os.Setenv("DB_PASSWORD", "super_secret_password")
var cfg Config
if err := envyaml.LoadConfig("config.yml", &cfg); err != nil {
log.Fatalf("Failed to load config: %v", err)
}
fmt.Printf("Database: %s@%s:%d/%s\n",
cfg.Database.Username,
cfg.Database.Host,
cfg.Database.Port,
cfg.Database.Database,
)
}With this config.yml:
database:
host: localhost
port: 5432
username: admin
password: ${DB_PASSWORD}
database: myapp
debug: falseOutput:
Database: admin@localhost:5432/myapp
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ YAML File │ │ Environment │ │ Go Struct │
│ │ │ Variables │ │ │
│ host: localhost│ │ │ │ Host: localhost│
│ port: 3606 │ ──► │ DB_PASSWORD= │ ──► │ Port: 3606 │
│ password: ${..}│ │ "secret123" │ │ Password: ... │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┴───────────────────────┘
envYaml
- Read - Parse your YAML configuration file
- Merge - Overlay environment variables using struct tags
- Validate - Ensure required variables are present
- Return - Provide a fully populated, type-safe config struct
This project uses Task for managing development tasks.
# Build the project
task build
# Run tests
task test
# Run tests with coverage
task test-coverage
# Clean generated files
task clean
# Run all tasks
task allWe love contributions! ❤️
- 🍴 Fork the repository
- 🌿 Create your feature branch (
git checkout -b feature/amazing-feature) - 💾 Commit your changes (
git commit -m 'Add amazing feature') - 📤 Push to the branch (
git push origin feature/amazing-feature) - 🎉 Open a Pull Request
Please feel free to:
- 🐛 Report bugs
- 💡 Suggest new features
- 📖 Improve documentation
- ⭐ Star the project if you find it useful!
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.