nixos-module-builder

What problem does it solve?

This guide eliminates guesswork and inconsistency when adding new NixOS or Home Manager modules by prescribing a repeatable "activate-by-enabling-option" module pattern so features remain opt-in, composable, and easy to maintain.

Core Features & Use Cases

• Opinionated Module Pattern: Shows how to declare options.modules.<category>.<name> with mkEnableOption and additional mkOption entries to expose sub-options and package variants.
• Conditional Configuration: Demonstrates using mkIf, mkMerge, optionals, and optionalAttrs to compose configuration safely based on enable flags and sub-options.
• Integration Workflow: Explains where to place modules in modules/nixos or modules/home-manager, how to add them to a category's default.nix import list, and how to enable them in hosts/<hostname>/default.nix or home/<username>/default.nix.
• Validation and Examples: Provides references for hardware, desktop, services, and virtualization patterns, plus commands to validate changes with nixos-rebuild and nix flake check.

Quick Start

Create a new module file in the appropriate modules/<category>/ directory that defines options.modules.<category>.<name>.enable with mkEnableOption, implements config guarded by mkIf cfg.enable, adds the file to the category default.nix imports, and enable it in the host or user modules to test with nixos-rebuild.