README
¶
Synthra examples
Runnable programs that complement the shorter snippets in example_test.go and the package overview on pkg.go.dev.
Progression
Start at the top and work down -- each example builds on concepts from the previous ones.
| Directory | What it shows |
|---|---|
| basic | YAML file + struct binding |
| environment | Environment-only config |
| webapp | YAML defaults + WEBAPP_* overrides + binding + Validate |
| jsonschema | WithJSONSchema validation on a file |
| customvalidator | WithValidator cross-field rule |
| dump | WithFileDumperAs + Dump of merged state |
| defaults | WithContent defaults, then file, then env |
| formats | WithFileAs with JSON + TOML |
| consul | WithIf(..., WithConsul(...)) (no Consul required for tests) |
| testing | synthratest.Config + source.NewMap in tests |
Quick start
cd examples/basic && go run .
cd examples/environment && WEBAPP_SERVER_HOST=localhost WEBAPP_SERVER_PORT=8080 \
WEBAPP_DATABASE_PRIMARY_HOST=db WEBAPP_DATABASE_PRIMARY_PORT=5432 \
WEBAPP_DATABASE_PRIMARY_DATABASE=myapp WEBAPP_AUTH_JWT_SECRET=secret \
WEBAPP_FEATURES_DEBUG_MODE=true go run .
cd examples/webapp && go run .
Tests
Every example ships with tests. Run them all at once:
go test ./examples/...
Docker (webapp)
From the repository root:
docker build -f examples/Dockerfile -t synthra-webapp-example .
docker run --rm synthra-webapp-example
The image uses the Go version pinned in Dockerfile (aligned with go.mod).
Environment variable naming
Examples use explicit prefixes (WEBAPP_, APP_, EDGE_, DEMO_). Strip the prefix, split on _, lowercase, and nest: WEBAPP_SERVER_READ_TIMEOUT becomes server.read.timeout.
Adding a new example
- Create a subdirectory with
main.go,README.md, and tests. - Link it from this file.
- Keep snippets copy-paste accurate (
gopherly.dev/synthraimports, real paths).
Directories
¶
| Path | Synopsis |
|---|---|
|
Package main shows YAML file loading and struct binding with Synthra.
|
Package main shows YAML file loading and struct binding with Synthra. |
|
Package main loads local YAML, optionally merges Consul KV, then env.
|
Package main loads local YAML, optionally merges Consul KV, then env. |
|
Package main demonstrates cross-field checks with synthra.WithValidator.
|
Package main demonstrates cross-field checks with synthra.WithValidator. |
|
Package main shows merge order: baked-in defaults, then file, then env.
|
Package main shows merge order: baked-in defaults, then file, then env. |
|
Package main writes the merged effective configuration to a YAML file.
|
Package main writes the merged effective configuration to a YAML file. |
|
Package main demonstrates loading configuration from environment variables with Synthra.
|
Package main demonstrates loading configuration from environment variables with Synthra. |
|
Package main loads JSON and TOML with explicit codecs via WithFileAs.
|
Package main loads JSON and TOML with explicit codecs via WithFileAs. |
|
Package main demonstrates JSON Schema validation on loaded configuration.
|
Package main demonstrates JSON Schema validation on loaded configuration. |
|
Package main demonstrates JSON Schema defaults and WithEnvSubst.
|
Package main demonstrates JSON Schema defaults and WithEnvSubst. |
|
Package main exists so `go run .` works; see README and *_test.go.
|
Package main exists so `go run .` works; see README and *_test.go. |
|
Package main demonstrates layered configuration (YAML defaults plus environment overrides), struct binding, and validation with Synthra.
|
Package main demonstrates layered configuration (YAML defaults plus environment overrides), struct binding, and validation with Synthra. |
Click to show internal directories.
Click to hide internal directories.