Axum Config

Configuration management for Axum applications. Load configuration from TOML files with environment variable support.

Features

• Load configuration from TOML files
• Environment variable interpolation (${VAR} and ${VAR:default})
• Integration with Axum as extractor
• File loading directly on config files (key = "file:path")

Installation

cargo add axum-config

Usage

1. Define configuration structure

use serde::Deserialize;
use axum_config::config;

#[config(key = "database")]
#[derive(Debug, Clone, Deserialize)]
pub struct DatabaseConfig {
    pub host: String,
    pub port: u16,
    pub user: String,
}

2. Create configuration file

config/config.toml:

[database]
host = "${DB_HOST:localhost}"
port = 5432
user = "${DB_USER:admin}"

3. Use in your application

use axum::{Router, routing::get, Extension};
use axum_config::{Config, ExtractConfig};
use std::sync::Arc;
use tokio::net::TcpListener;

#[tokio::main]
async fn main() {
    let config = Config::builder()
        .add_file("config/config.toml")
        .build()
        .expect("Failed to load config");

    let app = Router::new()
        .route("/", get(handler))
        .layer(Extension(config));

    let server_config = config.expect::<ServerConfig>();
    let addr = format!("{}:{}", server_config.host, server_config.port));

    let listener = TcpListener::bind(&addr)
        .await
        .unwrap();

    axum::serve(listener, app).await.unwrap();
}

// If your handlers are separated into another modules,
// it's recommended to rename `ExtractConfig` to `Config` for clarity.
// use axum_config::ExtractConfig as Config;

async fn handler(
    ExtractConfig(db_config): ExtractConfig<DatabaseConfig>,
) -> impl IntoResponse {
    format!("DB: {}:{}", db_config.host, db_config.port)
}

Configuration Loading

Use Config::builder() to specify configuration files. Files can be optional (loaded if present) or required (must exist).

let config = Config::builder()
    .add_file("config/config.toml")  // optional
    .add_required_file("secrets.toml")  // required
    .build()?;

Files are merged in order, with later files overriding earlier ones.

Environment variables

Supports interpolation in TOML with default values:

[server]
host = "${HOST:0.0.0.0}"      # Uses HOST or defaults to "0.0.0.0"
port = "${PORT}"              # Requires PORT to be defined
database_url = "${DATABASE_URL}/my_database"  # Requires DATABASE_URL and appends "/my_database"

Config Methods

Extractor Methods

Note: Enable the validation feature in your Cargo.toml for ExtractValidatedConfig: axum-config = { version = "*", features = ["validation"] }