Skip to main content
Flake modules provide the foundation for the entire configuration framework. They define build systems, development shells, custom packages, library functions, and automated checks that ensure your NixOS configuration works correctly.

​
What flake modules provide

Flake modules operate at the flake level and configure how your entire system is built and tested. Unlike other module categories that configure system or user settings, flake modules define the infrastructure that makes everything else work.

Build configuration

System architecture support, package overlays, and build arguments

Development tools

Dev shells with formatters, linters, and development dependencies

Custom packages

Framework-specific packages like documentation generators and installers

Library functions

Helper functions for secrets, hardware detection, and configuration templates

​
Module structure

Flake modules are organized into several subcategories:
Defines the base arguments passed to the flake, including supported systems and nixpkgs configuration.
modules/flake/args.nix
{ inputs, ... }:
{
  # set the output systems for this flake
  systems = [
    "x86_64-linux"
    "aarch64-linux"
    "aarch64-darwin"
  ];

  perSystem = { system, ... }: {
    _module.args.pkgs = import inputs.nixpkgs {
      inherit system;
      config = {
        allowUnfree = true;
        allowUnsupportedSystem = true;
      };
    };
  };
}
This configuration:
  • Supports x86_64 and ARM Linux systems
  • Supports Apple Silicon Macs (aarch64-darwin)
  • Enables unfree packages like proprietary software
  • Allows building for unsupported systems when needed
Custom library functions that extend NixOS capabilities throughout the framework.Available libraries:
  • helpers.nix - File import utilities, git URL helpers, SSH key management
  • secrets.nix - Secrets management with sops-nix integration
  • services.nix - Service configuration helpers
  • hardware.nix - Hardware detection and configuration
  • validators.nix - Input validation functions
  • template/ - XDG directory templates and configuration scaffolding
Example: Git URL aliases
# From lib/helpers.nix
giturl {
  domain = "github.com";
  alias = "gh";
}
# =>
# "https://github.com/".insteadOf = "gh:";
# "ssh://[email protected]/".pushInsteadOf = "gh:";
Example: SSH public keys
mkPubs "github.com" [
  {
    type = "ed25519";
    key = "AAAAC3NzaC1lZDI1NTE5AAAA...";
  }
]
CI/CD checks that validate your configuration before deployment.Available checks:
  • formatting.nix - Ensures code is properly formatted
  • lib.nix - Tests library functions
These checks run automatically in CI pipelines to catch errors early.
Framework-specific packages that extend NixOS functionality.Available packages:
  • docs/ - Documentation generation system (this documentation!)
  • iztaller/ - Installation wizard and system bootstrapper
These packages are built by the flake and made available to your systems.
Programs and tools for the development shell.Available programs:
  • formatter.nix - Code formatting with nixfmt, keep-sorted, treefmt
  • shell.nix - Development shell with build tools and utilities
Access these tools by running nix develop in your configuration directory.

​
Usage example

Flake modules are imported automatically when you use the flake. You don’t typically interact with them directly unless you’re extending the framework.
flake.nix
{
  inputs = {
    garden.url = "github:isabelroses/dotfiles";
  };

  outputs = { garden, ... }: {
    # The flake modules are already loaded
    # They provide lib, packages, checks, etc.
    nixosConfigurations.myhost = garden.lib.nixosSystem {
      modules = [ ./configuration.nix ];
    };
  };
}

​
Key features

​
Multi-architecture support

The flake supports building for multiple architectures out of the box:
  • x86_64-linux - Standard Intel/AMD Linux systems
  • aarch64-linux - ARM Linux systems (Raspberry Pi, cloud ARM instances)
  • aarch64-darwin - Apple Silicon Macs

​
Development shell

Enter the development environment to access all build tools: 
nix develop
This provides:
  • Code formatters (nixfmt, prettier, keep-sorted)
  • Build tools (git, just, direnv)
  • Documentation generators
  • Testing utilities

​
Custom library functions

The framework provides dozens of helper functions that simplify common NixOS configuration tasks. These are available throughout your configuration as lib.garden.*.

​
Next steps

NixOS modules

System-level configuration for NixOS

Base modules

Shared configuration between NixOS and Darwin

Build docs developers (and LLMs) love

Get started for freeTalk to us