Crate gonfig

Gonfig

A unified configuration management library for Rust that seamlessly integrates environment variables, configuration files, and CLI arguments.

Features

• Multiple Configuration Sources: Environment variables, config files (JSON/YAML/TOML), and CLI arguments
• Flexible Prefix Management: Configure environment variable prefixes at struct and field levels
• Derive Macro Support: Easy configuration with #[derive(Gonfig)]
• Merge Strategies: Deep merge, replace, or append configurations
• Type Safety: Fully type-safe configuration with serde
• Validation: Built-in validation support for your configurations
• Granular Control: Enable/disable sources at struct or field level

Quick Start

Using the Derive Macro (Recommended)

use gonfig::Gonfig;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Gonfig)]
#[Gonfig(env_prefix = "APP")]
struct Config {
    // Environment variable: APP_DATABASE_URL
    database_url: String,
     
    // Environment variable: APP_PORT
    port: u16,
     
    // Skip this field from configuration
    #[skip]
    #[serde(skip)]
    runtime_data: Option<String>,
}

fn main() -> gonfig::Result<()> {
    std::env::set_var("APP_DATABASE_URL", "postgres://localhost/myapp");
    std::env::set_var("APP_PORT", "8080");
     
    let config = Config::from_gonfig()?;
    println!("Database: {}", config.database_url);
    println!("Port: {}", config.port);
    Ok(())
}

Using ConfigBuilder for Advanced Configuration

use gonfig::{ConfigBuilder, MergeStrategy};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct AppConfig {
    name: String,
    port: u16,
    debug: bool,
}

fn main() -> gonfig::Result<()> {
    let config: AppConfig = ConfigBuilder::new()
        .with_merge_strategy(MergeStrategy::Deep)
        .with_env("APP")
        .with_file("config.json")?
        .with_cli()
        .build()?;
     
    println!("Loaded configuration: {:?}", config);
    Ok(())
}

Configuration Sources

Environment Variables

Environment variables are automatically mapped to struct fields using configurable prefixes:

use gonfig::{Environment, ConfigBuilder};
use serde::Deserialize;

#[derive(Deserialize)]
struct Config {
    database_url: String,
    port: u16,
}

fn main() -> gonfig::Result<()> {
    std::env::set_var("MYAPP_DATABASE_URL", "postgres://localhost/db");
    std::env::set_var("MYAPP_PORT", "3000");

    let config: Config = ConfigBuilder::new()
        .with_env("MYAPP")
        .build()?;
    Ok(())
}

Configuration Files

Support for JSON, YAML, and TOML configuration files:

use gonfig::{ConfigBuilder, ConfigFormat};
use serde::Deserialize;

#[derive(Deserialize)]
struct Config {
    database: DatabaseConfig,
    server: ServerConfig,
}

#[derive(Deserialize)]
struct DatabaseConfig {
    url: String,
    pool_size: u32,
}

#[derive(Deserialize)]
struct ServerConfig {
    host: String,
    port: u16,
}

fn main() -> gonfig::Result<()> {
    let config: Config = ConfigBuilder::new()
        .with_file("app.yaml")?
        .build()?;
    Ok(())
}

CLI Arguments

Integrate with clap for command-line argument parsing:

use gonfig::{ConfigBuilder, Cli};
use serde::Deserialize;
use clap::Parser;

#[derive(Parser, Deserialize)]
struct Config {
    #[arg(long, env = "DATABASE_URL")]
    database_url: String,
     
    #[arg(short, long, default_value = "8080")]
    port: u16,
}

fn main() -> gonfig::Result<()> {
    let config: Config = ConfigBuilder::new()
        .with_cli()
        .build()?;
    Ok(())
}

Derive Attributes

Struct-level attributes:

• #[Gonfig(env_prefix = "PREFIX")] - Set environment variable prefix
• #[Gonfig(allow_cli)] - Enable CLI argument support
• #[Gonfig(allow_config)] - Enable config file support

Field-level attributes:

• #[gonfig(env_name = "CUSTOM_NAME")] - Override environment variable name
• #[gonfig(cli_name = "custom-name")] - Override CLI argument name
• #[skip] or #[skip_gonfig] - Skip this field from all configuration sources

Environment Variable Naming

Environment variables follow a consistent hierarchical pattern:

• With prefix: {PREFIX}_{STRUCT_NAME}_{FIELD_NAME}
  • Example: prefix APP, struct Config, field database_url → APP_CONFIG_DATABASE_URL
• Without prefix: {STRUCT_NAME}_{FIELD_NAME}
  • Example: struct Config, field database_url → CONFIG_DATABASE_URL
• With field override: Uses the exact override value
  • Example: #[gonfig(env_name = "DB_URL")] → DB_URL
• Nested structs: Each level adds to the path
  • Example: APP_PARENT_CHILD_FIELD

Re-exports

pub use builder::ConfigBuilder;

pub use cli::Cli;

pub use config::Config;

pub use config::ConfigFormat;

pub use environment::Environment;

pub use error::Error;

pub use error::Result;

pub use merge::MergeStrategy;

pub use source::ConfigSource;

pub use source::Source;

Modules

builder

Configuration builder for assembling multiple configuration sources.

cli

Command-line interface integration using clap.

config

Configuration file parsing and handling.

environment

Environment variable configuration source.

error

Error types and result aliases for configuration operations.

merge

Configuration merging strategies and utilities.

source

Core traits and types for configuration sources.

Structs

Prefix

A configuration prefix used for environment variables

Derive Macros

Gonfig