Customization Module Options - bcl1713/nixos GitHub Wiki

Module Configuration Options

This guide explains how to customize modules through their configuration options, covering option types, usage patterns, and common customizations.

Understanding Module Options

Each module in this configuration follows a consistent pattern for declaring and using options. Understanding this pattern will help you customize effectively.

Option Declaration Structure

Options are declared using Nix's module system. A typical option looks like:

options.userPackages.category.module = {
  enable = mkOption {
    type = types.bool;
    default = true;
    description = "Whether to enable this module";
  };
  
  setting = mkOption {
    type = types.str;
    default = "default-value";
    description = "Description of what this setting controls";
  };
};

Types of Configuration Options

Common option types include:

  • Boolean options (types.bool): Enable/disable features
  • String options (types.str): Text configurations
  • Integer options (types.int): Numeric values
  • Enum options (types.enum): Selection from predefined values
  • Attribute sets (types.attrs): Complex nested configurations
  • Lists (types.listOf): Collections of values

Options and Defaults

Module options typically follow these patterns:

  1. Most modules have an enable option that defaults to true
  2. Sensible defaults are provided for all options
  3. Options are grouped logically by feature or component
  4. Dependencies between options are handled internally

Core Module Options

Window Manager (Hyprland)

Key customization options:

userPackages.wm.hyprland = {
  enable = true;  # Enable/disable Hyprland
  
  swaylock = {
    enable = true;  # Enable screen locking
  };
  
  swayidle = {
    enable = true;  # Enable automatic idle actions
    timeouts = {
      lock = 300;  # Seconds before locking screen
      dpms = 600;  # Seconds before turning off display
    };
  };
};

Status Bar (Waybar)

Waybar can be customized with:

userPackages.wm.waybar = {
  enable = true;
};

# For system monitoring in waybar:
userPackages.utilities.system.monitoring = {
  enable = true;
  waybar = {
    enable = true;
    cpu.enable = true;
    memory.enable = true;
    disk.enable = true;
    temperature.enable = true;
  };
};

Terminal (Kitty)

Terminal options include:

userPackages.apps.terminal.kitty = {
  enable = true;
  font = {
    family = "FiraCode Nerd Font Mono";
    size = 12;  # Set to null for default
  };
  theme = "Catppuccin-Mocha";
};

Editors (Neovim)

Neovim can be configured with:

userPackages.editors.neovim = {
  enable = true;
  plugins = {
    enable = true;
    lsp.enable = true;
    git.enable = true;
    markdown.enable = true;
  };
};

Application Module Options

Browser Configuration

Firefox can be customized with:

userPackages.apps.browser.firefox = {
  enable = true;
  privacy = {
    enable = true;
    disableTelemetry = true;
    disablePocket = true;
    dnsOverHttps = {
      enable = true;
      providerUrl = "https://dns.quad9.net/dns-query";
    };
  };
};

Development Applications

Git configuration options:

userPackages.apps.development.git = {
  enable = true;
  userName = "Your Name";
  userEmail = "[email protected]";
  defaultBranch = "main";
  enableCommitTemplate = true;
  enableCommitHooks = true;
};

GitHub CLI configuration:

userPackages.development.github = {
  enable = true;
  enableCompletions = true;
};

Utility Module Options

System Monitoring

System monitoring can be configured with:

userPackages.utilities.system.monitoring = {
  enable = true;
  topTools.enable = true;  # htop, btop, etc.
  graphical.enable = true; # GUI monitoring tools
};

Disk Usage Tools

Disk usage utilities can be configured with:

userPackages.utilities.diskUsage = {
  enable = true;
  interactiveTools.enable = true;
  graphicalTools.enable = true;
  duplicateFinder.enable = true;
  cleanupTools.enable = true;
};

System Updates

System update management options:

userPackages.utilities.systemUpdates = {
  enable = true;
  homeManager = {
    enable = true;
    frequency = {
      time = "04:30";
      weekday = "weekly";
    };
  };
  system = {
    allowReboot = false;
  };
  notifications = {
    enable = true;
    beforeUpdate = true;
    afterUpdate = true;
  };
  maintenance = {
    garbageCollection = {
      enable = true;
      maxAge = 30;  # days
      frequency = "weekly";
    };
    optimizeStore = true;
  };
};

Power Management

Power management options:

userPackages.utilities.powerManagement = {
  enable = true;
  defaultProfile = "balanced";  # balanced, performance, powersave
  keybinding = "SUPER, F7";
  indicator.enable = true;
};

Finding and Setting Options

Locating Available Options

To find available options:

  1. Browse the module files: Check the user/packages/ directory
  2. Look for option declarations: Find options.userPackages... sections
  3. Check the wiki reference: See Configuration-Options-Reference

Setting Option Values

To set options, edit your personal profile:

  1. Open profiles/personal/home.nix
  2. Add or update the corresponding configuration section
  3. Apply changes with home-manager switch --flake ~/.dotfiles/

Testing Option Changes

Before applying changes to your main configuration:

# Test build without applying
home-manager build --flake ~/.dotfiles/

# Check for errors in the build output

Examples

Disabling a Feature

To disable a feature that's enabled by default:

userPackages.utilities.bitwarden.enable = false;

Changing Default Values

To change a default setting:

userPackages.utilities.systemUpdates.maintenance.garbageCollection.maxAge = 14;

Enabling Optional Features

To enable a feature that's not enabled by default:

userPackages.utilities.powerManagement.indicator.enable = true;

Next Steps