A simple Nix dendritic config

2026-04-17

I run NixOS on both my desktop and laptop. Until a few weeks ago, all my Nix code lived in a single configuration.nix file that accepted the machine hostname as an argument. Over time, entropy did its work, and that file turned into a spaghetti mess.

After seeing the Nix Dendritic Pattern mentioned in several places, I wondered whether it would make sense for my rather simple setup, or if it would be overkill. Spoiler: even for my simple setup, it helped me better organize my system configuration.

There are great guides, posts, and examples in the wild to learn about the dendritic pattern and its components. Nevertheless, I had a hard time applying the abstract concepts to my concrete problem. I often had to dive into implementation code to fully understand some parts.

In this post, I explain how I used the dendritic pattern to solve my particular problem: NixOS + Home Manager on both a desktop and a laptop, with two users. I trimmed my configuration to the minimum while keeping all features. The goal is a complete but simple example that we can walk through and explain in full. I hope that after grasping this example, you should be able to create a solution tailored to your own requirements with the help of other sources.

I assume familiarity with Nix, NixOS, and flakes.

All the code implementing the systems configuration is available here:

Get source

/etc/nixos
├── flake.nix
└── modules
    ├── base
    │   ├── configuration.nix
    │   ├── overlays.nix
    │   └── packages.nix
    ├── flake-parts.nix
    ├── hosts
    │   ├── home-desktop
    │   │   ├── default.nix
    │   │   └── filesystem.nix
    │   └── renato-notebook
    │       ├── default.nix
    │       └── filesystem.nix
    └── users
        ├── helena.nix
        └── renatofg
            ├── default.nix
            └── _dotfiles
                └── starship.toml

We’ll cover the key concepts first, then walk through the code.

Contents

Key concepts
Code walkthrough
Wrapping it up: Dendritic Pattern

Key concepts

In short: we organize our configuration as a collection of modules that get merged together.

But to understand how this works, we first need to cover a few core concepts, the building blocks we use to structure our system configuration following the dendritic pattern.

Flake

We use all those files to structure our NixOS system configuration. At the end of the day, all that code gets evaluated into a flake output set. Specifically, the system configuration lives under the nixosConfigurations.<hostname> attribute.

All code structured following the dendritic pattern will be transformed to a flake output set.

We write our configuration as Flake Parts modules spread across multiple .nix files following the dendritic pattern. These files are imported and passed to the mkFlake function, which evaluates them into the final flake outputs.

Module

The module is the fundamental unit upon which everything else is built. We break our configuration into “module files,” where each file configures a specific feature. How broad or narrow each feature is, and how many you create, is up to you. We’ll discuss this further in the following sections.

At its core, a module is a function receiving an attribute set as input and evaluating to another attribute set. Optionally, instead of being a function, a module can be just a plain attribute set (like Module C). In this case, a module { A } will behave the same as the constant function args: { A }.

Once we split our configuration into multiple modules, we can run nixos-rebuild to reconfigure our NixOS machine. The module system combines all those modules into one. When evaluated, it produces the final merged attribute set.

During evaluation, multiple modules are merged into one, producing an attribute set that is the union of all individual attributes.

When merging modules, nested sets merge recursively (attribute by attribute), and lists are concatenated. However, if two modules define the same scalar value, it raises an error.

If we have these three modules:

{ pkgs, ... }:
{
  networking.wireless.enable = true;

  environment.systemPackages = [
    pkgs.nixd
    pkgs.emacs
    pkgs.git
  ];
}

Nix

Module A

{ pkgs, ... }:
{
  networking.wireless = {
    dbusControlled = true;
    fallbackToWPA2 = true;
  };

  environment.systemPackages = [
    pkgs.pandoc
  ];
}

Nix

Module B

{
  networking.hostName = "home-desktop";
}

Nix

Module C

After merging them, the result will be:

{ pkgs, ... }:
{
  networking = {
    wireless = {
      enable = true;
      dbusControlled = true;
      fallbackToWPA2 = true;
    };
    hostName = "home-desktop";
  };

  environment.systemPackages = [
    pkgs.nixd
    pkgs.emacs
    pkgs.git
    pkgs.pandoc
  ];
}

Nix

Everything discussed so far applies to all modules. However, there are different types of modules, distinguished by their input and output sets. Below we cover the three module types we’ll use: NixOS modules, Home Manager modules, and Flake Parts modules.

NixOS modules

NixOS modules configure the system. They are functions that receive an attribute set { config, options, pkgs, lib, modulesPath, ... } (the official wiki describes each argument) and evaluates to a set with NixOS options like services.*, users.*, networking.*, boot.*, etc. (See Appendix A for a full list.)

Here’s an example:

{ pkgs, ... }:
{
  environment.systemPackages = [
    pkgs.nixd
    pkgs.git
    pkgs.emacs-with-packages
  ];

  services.openssh.enable = true;

  users.users.renatofg = {
    isNormalUser = true;
    extraGroups = [ "wheel" "networkmanager" ];
  };
}

Nix

This module sets three options: environment.systemPackages (system-wide packages), services.openssh.enable (enable SSH daemon), and users.users.renatofg (user account configuration).

A classic example of a NixOS module is /etc/nixos/configuration.nix, created during a fresh install.

Home Manager modules

Home Manager modules configure the user environment (dotfiles, programs, user services). Like NixOS modules, they are functions that receive an attribute set { pkgs, lib, config, options, modulesPath, osConfig, ... } (see the official documentation for details) and evaluates to a set with options like home.*, programs.*, services.* (user-level), xdg.*, etc. (See Appendix A for a full list.)

Here’s an example:

{ pkgs, osConfig, ... }:
{
  home.stateVersion = "24.05";

  programs.git = {
    enable = true;
    userName = "Renato Garcia";
    userEmail = "foo@example.com";
  };

  programs.starship = {
    enable = true;
    settings = builtins.fromTOML (builtins.readFile ./_dotfiles/starship.toml);
  };

  # Access NixOS config when integrated
  home.packages = lib.optionals osConfig.services.xserver.enable [
    pkgs.alacritty
  ];
}

Nix

Home Manager has its own module evaluation. It can run standalone or integrated with NixOS. When integrated via home-manager.users.<name>, each user’s configuration is evaluated separately from the system configuration. The osConfig argument provides read-only access to the NixOS configuration, letting you make Home Manager settings conditional on system settings.

Flake Parts modules

Flake Parts modules differ from NixOS and Home Manager modules. Instead of configuring systems or users, they structure the flake itself, using the module system to organize flake outputs.

Like other modules, they are functions that receive an attribute set { self, config, options, lib, inputs, ... } and evaluate to another attribute set. (See the documentation for input arguments and output options.)

The Flake Parts library has broad applications, but for our purposes we only need three options: flake.modules.<class>.<aspect>, flake.nixosConfigurations.<hostname>, and perSystem.overlayAttrs.

`flake.modules.<class>.<aspect>`

This option collects our NixOS modules and Home Manager modules. The <class> attribute designates the module type, either nixos or homeManager (other classes exist but we won’t use them here). The <aspect> attribute designates the feature being configured.

For example: common configuration shared by all hosts goes in the base aspect (example), user-specific configuration in the helena aspect (example), and a complete host configuration in the home-desktop aspect (example).

You could also create an aspect for a specific service like ssh:

{ inputs, config, ... }:
{
  flake.modules.nixos.ssh = {
    # A NixOS module: setup OpenSSH server, firewall-ports, etc.
  };

  flake.modules.homeManager.ssh = {
    # A Home Manager module: setup ~/.ssh/config, authorized_keys,
    # private keys secrets, etc.
  };
}

Nix

The <class> name must match a configuration class: nixos, homeManager, etc. This determines what module type to assign. For a nixos class, assign NixOS modules; for homeManager, assign Home Manager modules.

All flake-parts modules will be merged, and each `flake.modules.<class>.<aspect>` attribute will be merged within it.

The <aspect> name is arbitrary, use as many as you need to organize your configuration. As with all modules, you can define multiple flake.modules.nixos.base attributes and they’ll be merged together. Access the merged result from any Flake Parts module via self.modules.nixos.base.

`flake.nixosConfigurations.<hostname>`

This option maps to the flake’s outputs.nixosConfigurations.<hostname> attribute. The <hostname> matches what you specify in nixos-rebuild switch --flake /etc/nixos#<hostname>.

Code walkthrough

Now let’s walk through the code.

flake.nix

Remember: the flake output set is our final result. When you run nixos-rebuild switch --flake /etc/nixos#home-desktop, it evaluates /etc/nixos/flake.nix, reads the configuration from outputs.nixosConfigurations.home-desktop, and reconfigures the system accordingly.

The function flake-parts.lib.mkFlake processes all our modules to create the host configurations:

Key concepts

Flake

Module

NixOS modules

Home Manager modules

Flake Parts modules

flake.modules.<class>.<aspect>

flake.nixosConfigurations.<hostname>

Code walkthrough

flake.nix

Flake Parts modules

flake.modules.<class>.<aspect>

flake.nixosConfigurations.<hostname>

perSystem.overlayAttrs

imports

systems

NixOS modules

Home Manager modules

Defining a host

Wrapping it up: Dendritic Pattern

`flake.modules.<class>.<aspect>`

`flake.nixosConfigurations.<hostname>`

`flake.modules.<class>.<aspect>`

`flake.nixosConfigurations.<hostname>`

`perSystem.overlayAttrs`

`imports`

`systems`