---
description: "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."
applyTo: '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