dendritic/.github/instructions/shared-modules.instructions.md

description, applyTo

description	applyTo
Use when defining or modifying reusable Nix modules outside modules/hosts. Covers flake.modules.nixos, flake.modules.homeManager, and flake.factory.user exports, and explains how shared modules differ from concrete host wiring.	modules/nixos/**/*.nix, modules/users/**/*.nix, modules/features/**/*.nix, modules/programs/**/*.nix, modules/services/**/*.nix, modules/nix-tools/**/*.nix

Shared Modules

Files outside modules/hosts generally define reusable building blocks, not concrete machines. In this repo, those files usually export one of these surfaces:

• flake.modules.nixos.<name> for reusable NixOS modules.
• flake.modules.homeManager.<name> for reusable Home Manager modules.
• config.flake.factory.user for factories that generate per-user module sets.
• flake.meta.* when the file owns reusable metadata that other modules consume.

Keep the boundary between shared modules and hosts clear:

• Shared modules should not define flake.nixosConfigurations.<name> or flake.homeConfigurations.<name>; those belong in modules/hosts.
• Prefer generic options, imports, and composition over host-specific literals.
• If a setting only makes sense for one machine, keep it in that host directory instead of moving it into a shared module.
• When a host imports a shared module, treat the shared module as part of the stable interface that multiple hosts may depend on.

Follow the existing export patterns in this repo:

• Simple reusable modules may export a single module directly, such as flake.modules.nixos.games.
• Cross-cutting features often live under modules/features even when they export flake.modules.nixos.* or flake.modules.homeManager.*.
• Program and service integrations commonly export one or both module types from a single file.
• User definitions under modules/users may export metadata plus paired NixOS and Home Manager modules for the same user.

For user modules specifically:

• Keep reusable user facts under flake.meta.users.<name> when other modules need to reference them.
• Prefer deriving the NixOS side from self.factory.user when the file already follows that pattern.
• Keep the user-facing Home Manager module in flake.modules.homeManager.<name> and let the factory or host wire it into a concrete configuration.
• Put user-specific authorized keys, identity, and shared defaults here rather than duplicating them across hosts.

Design shared modules as composable interfaces:

• Import other shared modules instead of copying option blocks.
• Add options or parameters when behavior needs to vary between hosts.
• Avoid embedding host-specific paths, hostnames, addresses, or secret file locations unless the file is intentionally host-local.
• Preserve exported attribute names even when the filename is different. In this repo, the path is not always the public API name.

Use nearby files as examples:

• modules/nixos/games.nix is a minimal shared NixOS module with no host wiring.
• modules/features/nixos-base.nix defines a reusable base system module that other hosts import.
• modules/users/john.nix combines flake.meta.users.john, a reusable NixOS user module, and a reusable Home Manager user module built around the user factory.
• modules/nix-tools/user.nix defines the flake.factory.user helper that shared user modules build on.

For reviews and answers, separate these concerns clearly:

• reusable module API and option design in shared module directories
• concrete host assembly in modules/hosts
• whether a change increases reuse or accidentally pulls machine-specific behavior into a shared layer