54 lines
3.6 KiB
Markdown
54 lines
3.6 KiB
Markdown
---
|
|
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 |