This document introduces the den framework at a high level. It explains what den is, its purpose as an aspect-oriented configuration system for Nix, and its core philosophy of Dendritic configurations—a pattern that enables writing configuration once that works across NixOS, nix-darwin, and Home Manager.
This overview provides the conceptual foundation for understanding den's architecture and workflow. For hands-on guidance, see Getting Started. For in-depth explanations of specific mechanisms, see Core Concepts.
Sources: README.md11 README.md22
den is an aspect-oriented configuration framework for Nix that enables managing NixOS, nix-darwin, and Home Manager configurations from a unified codebase. It solves the problem of configuration duplication when deploying the same software across different platforms (Linux, macOS) and contexts (system-level, user-level).
The framework introduces three key innovations:
includes to build complete configurationsTraditional Approach vs. den: In traditional Nix setups, you maintain separate configurations for each platform. With den, you write configuration once in an aspect, and it automatically contributes to the appropriate platforms.
Sources: README.md11 README.md22-24
The term Dendritic (from dendrites in neural networks) describes den's core pattern: a single configuration module branches out to multiple target platforms.
In den, an aspect can define configurations for three "classes":
| Class | Purpose | Example Use Case |
|---|---|---|
nixos | NixOS system configuration | Package installation, system services, networking |
darwin | nix-darwin system configuration | Homebrew packages, macOS defaults, system services |
homeManager | Home Manager user environment | Dotfiles, user programs, shell configuration |
When you deploy a configuration to a specific host or home, den automatically selects only the relevant class configurations.
Example: A vim configuration defined once in homeManager works on both Linux and macOS hosts, while platform-specific settings (Linux package management, macOS Homebrew) remain in their respective class sections.
Sources: README.md22 README.md132-150 templates/default/modules/den.nix1-169
den operates through a layered architecture that transforms user declarations into platform-specific Nix outputs.
Declaration Layer: Users define hosts and homes in den.hosts and den.homes. Each definition creates a corresponding aspect.
Aspect Layer: Aspects are modular configuration units. They compose via includes to form dependency chains.
Processing Layer: The parametric system wraps functions and uses canTake introspection to match functions with available context. Dependency functions progressively add context as they traverse the aspect chain.
Base Layer: Built-in batteries (den.provides) and base modules (den.base) provide common functionality and module imports.
Output Layer: Final platform-specific configurations are assembled into nixosConfigurations, darwinConfigurations, and homeConfigurations.
Sources: modules/aspects/dependencies.nix1-100 modules/lib/parametric.nix1-50 modules/base/conf.nix1-20
den's functionality is organized into several key modules and subsystems:
| Component | Location | Purpose |
|---|---|---|
den.hosts | modules/_types.nix1-100 | Schema for defining system hosts with users |
den.homes | modules/_types.nix1-100 | Schema for standalone Home Manager configurations |
den.aspects | modules/aspects/aspects-config.nix1-50 | Aspect definition and composition system |
den.lib.parametric | modules/lib/parametric.nix1-50 | Parametric function wrapper |
den.lib.canTake | modules/lib/canTake.nix1-30 | Function introspection for context matching |
den.provides | modules/aspects/provides/ | Built-in batteries (opt-in functionality) |
den._ | modules/aspects/provides/ | Alias for den.provides |
den.base | modules/base/ | Base modules with common imports |
den.namespace | modules/namespace.nix1-50 | Namespace system for aspect sharing |
Sources: modules/_types.nix1-100 modules/aspects/aspects-config.nix1-50 modules/lib/parametric.nix1-50 modules/aspects/provides/
Here's a minimal example showing den's core concepts in practice:
templates/examples/modules/_example/hosts.nix1-10
templates/default/modules/den.nix110-150
The same vim configuration in homeManager deploys to all three targets, while platform-specific settings remain isolated.
Sources: README.md89-104 templates/default/modules/den.nix110-150
den integrates with the standard Nix flake workflow but adds structured conventions for organizing configurations.
Project Initialization: Use templates to bootstrap a new project:
Development Cycle:
modules/nix flake check to validatenix run .#vm (if available)Integration Points:
Sources: templates/default/flake.nix1-30 README.md56-66
den provides four templates for different use cases:
| Template | Purpose | Location |
|---|---|---|
default | Batteries-included starting point with examples | templates/default/ |
minimal | Bare-bones structure for experienced users | templates/minimal/ |
examples | Test suite demonstrating all features | templates/examples/ |
bogus | Template for bug reproduction and reporting | templates/bogus/ |
Each template includes a modules/ directory structure and demonstrates different patterns for organizing configurations.
Sources: README.md74-79 templates/
To understand den's core concepts in depth, see Core Concepts.
To start using den immediately, see Getting Started.
For comprehensive configuration guidance, see Configuration Guide.
For advanced features like namespaces and custom providers, see Advanced Topics.
Sources: README.md1-182
Refresh this wiki
