Configuration & Feature Design
Separate compile-time Cargo features from runtime configuration. Load settings once at startup with validation; gate optional integrations with features.
//
Search across all documentation pages
Separate compile-time Cargo features from runtime configuration. Load settings once at startup with validation; gate optional integrations with features.
[features]
default = ["metrics"]
metrics = ["dep:prometheus"]#[derive(serde::Deserialize)]
struct Settings {
database_url: String,
port: u16,
}When to reach for this: Multi-environment deploys and optional compile-time backends.
let settings = Settings::parse()?; // env + defaults
let pool = PgPoolOptions::new().connect(&settings.database_url).await?;
#[cfg(feature = "metrics")]
prometheus::init();Settings validates port range in parse().env local onlymetrics trims deps in minimal buildsconfig crate layers files: config/default.toml + config/production.toml + env overrides. Document each env var in README.
full, minimal.Arc<Settings> reload policy documented.deny_unknown_fields + validate fn.| Alternative | Use When | Don't Use When |
|---|---|---|
| figment | layered sources | tiny CLI |
| clap env | CLI+server hybrid | many nested settings |
SIGHUP reload for non-secret fields; secrets need restart.
All config in env; files for local dev only.
Settings::test() with dummy URLs in tests module.
Flatten CLI overrides onto Settings for admin tools.
README matrix: feature -> deps -> use case.
Embed config at compile or JS injection at runtime.
Mount files read by config crate path.
Separate namespace + settings prefix per env.
Log non-secret effective config at startup (redacted).
Support old env alias one release with deprecation log.
Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.
Reviewed by Chris St. John·Last updated Jul 16, 2026