This document provides a high-level introduction to the den framework, explaining its purpose as an aspect-oriented, context-driven Nix configuration system. It covers the fundamental architecture, major components, and how they work together to manage NixOS, Darwin, and Home Manager configurations.
Den allows creating parametric configurations by taking the Dendritic pattern to the function-level README.md14-16 These configurations become specific when applied to particular infrastructure entities (hosts/users), while allowing re-usable aspects to be shared across flakes and non-flake projects README.md18-19
Sources: README.md14-20 docs/src/content/docs/index.mdx56-69 docs/src/content/docs/explanation/core-principles.mdx8-14
Den operates as two complementary layers:
den.lib): A domain-agnostic system for activating Nix configuration aspects via context transformations docs/src/content/docs/index.mdx59-60 It can be used to configure anything Nix-configurable (Terraform, Neovim, etc.) and works with or without flakes README.md71-75 docs/src/content/docs/index.mdx103-109Den embraces existing Nix choices and does not impose a specific module system; it is compatible with flake-parts, evalModules, or traditional configuration.nix setups README.md75 docs/src/content/docs/index.mdx117-121
Sources: README.md69-75 docs/src/content/docs/index.mdx59-65 docs/src/content/docs/index.mdx99-134 docs/src/content/docs/index.mdx147-151 AGENTS_EXAMPLE.md44-48
Users interact with Den through three main entry points defined in the module system:
| Configuration Entry | Purpose | Reference |
|---|---|---|
den.hosts.<system>.<name> | Define machines (NixOS/Darwin) | docs/src/content/docs/index.mdx162 |
den.homes.<system>.<name> | Define standalone home environments | docs/src/content/docs/index.mdx162 |
den.aspects.<name> | Define reusable configuration units | README.md28 |
These entries are validated by den.schema and processed through den.ctx pipelines to produce standard Nix outputs like nixosConfigurations docs/src/content/docs/index.mdx161-167
Sources: README.md25-42 docs/src/content/docs/index.mdx160-166 docs/src/content/docs/explanation/context-system.mdx39-57 AGENTS_EXAMPLE.md111-130
The following diagram maps the relationship between natural language concepts and the code entities that implement them.
Diagram: Natural Language to Code Entity Mapping
Sources: README.md48-63 docs/src/content/docs/index.mdx152-159 docs/src/content/docs/explanation/core-principles.mdx32-46 AGENTS_EXAMPLE.md44-48
Den organizes configurations by class—a named category of configuration (e.g., nixos, homeManager). An aspect is "Dendritic" because it can contain modules for multiple classes simultaneously docs/src/content/docs/explanation/core-principles.mdx52-63
| Class | Target System | Implementation Note |
|---|---|---|
nixos | NixOS | Standard NixOS modules README.md29 |
darwin | nix-darwin | macOS system configuration README.md30 |
homeManager | Home Manager | User-level environment README.md32 |
hjem | Hjem | Alternative home manager README.md31 |
maid | Maid | Alternative home manager docs/src/content/docs/explanation/context-system.mdx32-33 |
user | User Management | Logic for creating system users AGENTS_EXAMPLE.md55 |
Sources: README.md25-32 docs/src/content/docs/index.mdx74-96 docs/src/content/docs/explanation/core-principles.mdx52-63 AGENTS_EXAMPLE.md52-61
The data flow bridges the gap between the declarative schema and the final system instantiation.
Diagram: Context Transformation and Resolution Flow
Sources: README.md52-63 docs/src/content/docs/index.mdx135-143 docs/src/content/docs/index.mdx152-167 docs/src/content/docs/explanation/core-principles.mdx32-46
The context pipeline transforms configuration through stages, walking the topology from host to user to home docs/src/content/docs/index.mdx164
den.ctx.host): Initial stage taking {host} docs/src/content/docs/explanation/core-principles.mdx101den.ctx.user): Derived stage taking {host, user} for each user docs/src/content/docs/explanation/core-principles.mdx107hm-user): Stage for home-manager or alternative home environments, often conditional on user settings docs/src/content/docs/explanation/core-principles.mdx110Aspects use parametric functions and builtins.functionArgs introspection to receive only the contexts they need docs/src/content/docs/index.mdx166 AGENTS_EXAMPLE.md62-65 For example, an aspect defined as { host, user }: { ... } will only be activated when both host and user context are available README.md28
Sources: README.md26-42 docs/src/content/docs/index.mdx74-80 docs/src/content/docs/explanation/context-system.mdx24-34 docs/src/content/docs/explanation/core-principles.mdx94-116 AGENTS_EXAMPLE.md62-72
Den provides several templates to facilitate different workflows and dependency management strategies README.md120-137
| Template | Primary Characteristics |
|---|---|
default | Flakes, flake-parts, Home Manager README.md122 templates/default/flake.nix5-21 |
minimal | Flakes, no flake-parts, no Home Manager README.md124 |
noflake | No Flakes, uses npins and with-inputs README.md126 |
nvf-standalone | Neovim apps, demonstrates non-OS configuration README.md128-129 |
microvm | MicroVM guest management and custom pipelines README.md130-131 |
bogus | Isolated test for bug reproduction README.md138-139 |
Sources: README.md115-139 templates/default/flake.nix1-23 AGENTS_EXAMPLE.md18-20
den.lib)The den.lib utility library provides the functional core of the system:
parametric: Defines aspects that adapt based on context AGENTS_EXAMPLE.md76-85aspects.resolve: The primary function to extract a specific class module from a resolved aspect DAG README.md57take: Utilities like take.atLeast or take.exactly to filter context before passing it to aspects AGENTS_EXAMPLE.md71__findFile: Implements the <aspect/path> angle bracket syntax for deep aspect lookups docs/src/content/docs/guides/angle-brackets.mdx14-16Sources: README.md57 docs/src/content/docs/index.mdx140 docs/src/content/docs/guides/angle-brackets.mdx24 AGENTS_EXAMPLE.md71-85