den

An Aspect is an attribute set that contains configuration modules for different Nix class types (such as nixos, homeManager, darwin, or hjem).

Instead of configuring a host by pushing modules downward, Den uses an aspect-oriented model where features (aspects) are the primary organizational unit. An aspect consolidates all class-specific configuration for a single cross-cutting concern (e.g., gaming or bluetooth).

Key distinction: Den Context vs NixOS Module Args Den context (e.g., { host }, { host, user }) is a set of parameters passed to an aspect function. This is not the same as NixOS module arguments ({ config, pkgs, lib, ... }). Den context is evaluated before module evaluation, which prevents infinite recursion loops common in traditional Nix configurations.

# An aspect configuring a single concern across different Nix classes
gaming = { host, user }: {
  nixos = { ... };
  homeManager = { ... };
  hjem = { ... };
  darwin = { ... };
}

In Den, an aspect is a function that takes a context (such as { host, user }) and returns configuration for multiple Nix classes simultaneously. Instead of scattering a single feature across separate nixos, darwin, or homeManager files, an aspect encapsulates the entire feature in one place.

Key characteristics of aspects:

• Composable: Aspects can include other aspects using the includes key.
• Nesting: Aspects can provide capabilities that other aspects can consume using the provides key.
• Conditional by Design: Because an aspect is a function of context, it only runs where the required context (like a user) exists, eliminating the need for explicit mkIf or enable flags.

# An aspect is a function of context that returns
# configuration for many Nix classes at once.
den.aspects.gaming = { host, user }: {
  nixos       = { pkgs, ... }: { programs.steam.enable = true; };
  darwin      = { pkgs, ... }: { /* ... */ };
  homeManager = { pkgs, ... }: { /* ... */ };

  includes = [ den.aspects.performance ];   # aspects compose
  provides.emulation = { nixos = { /* ... */ }; };  # and nest
};

The den.schema.{host,user,home} modules allow you to define meta-configuration that applies to all entities of that type. This is used to specify features for all hosts, add schema options with defaults, or apply global configuration.

• Global Features: Use den.schema.host.<feature>.enable = true to enable a feature across all hosts.
• Custom Options: Define new options with defaults using den.schema.<type>.
• Global Attributes: Use den.schema.conf to apply attributes to every host, user, and home.

{
  # Enable a feature for all hosts
  den.schema.host.home-manager.enable = true;

  # Add a new schema option with a default for all users
  den.schema.user = { user, lib, ... }: {
    options.groupName = lib.mkOption { default = user.userName; };
  };

  # Apply a configuration attribute to every host, user, and home
  den.schema.conf = {
    options.copyright = lib.mkOption { default = "Copy-Left"; };
  };
}

A parametric aspect is an aspect defined as a function where the arguments are pipeline context values (e.g., host, user, home, or custom entity kinds). Den uses the function's argument pattern to determine when to activate the aspect.

Key behaviors:

• Automatic Activation: The aspect only runs in contexts where all required arguments are available. No mkIf or enable flags are required; the argument shape is the condition.
• Static Attrs: If an aspect is a static attribute set (not a function), it is always included regardless of context.

Examples

Single argument activation:

# This aspect only activates in {host} contexts
den.aspects.networking = { host, ... }: {
  nixos.networking.hostName = host.name;
};

Multi-argument activation:

# This only activates when both {host, user} are present
den.aspects.user-groups = { host, user, ... }: {
  nixos.users.users.${user.userName}.extraGroups = [ "wheel" ];
};

Standalone context activation:

# This only activates for standalone {home} contexts
den.aspects.shell-config = { home, ... }: {
  homeManager.programs.zsh.enable = true;
};

To establish a relationship between a User and a Host, use the provides namespace within an aspect definition. The target of the provides key determines where the configuration is delivered:

• provides.<name>: Delivers configuration to the specific host or user named <name>.
• provides.to-hosts: Delivers configuration to every host where the aspect's owner lives.
• provides.to-users: Delivers configuration to every user residing on the host where the aspect's owner lives.

Note that provides keys registered on a user aspect are subtree-scoped: they reach that user and its hosts, but they cannot reach sibling users on the same host. To configure multiple users or perform per-user selection, you must register the provides key on the host aspect.

# user aspect provides to a specific host or to all hosts where it lives
den.aspects.tux = {
  provides.igloo.nixos.programs.emacs.enable = true;
  provides.to-hosts = { host, ... }: {
    nixos.programs.nh.enable = host.name == "igloo";
  };
};

# host aspect provides to a specific user or to all its users
den.aspects.igloo = {
  provides.alice.homeManager.programs.vim.enable = true;
  provides.to-users = { user, ... }: {
    homeManager.programs.helix.enable = user.name == "alice";
  };
};