terlar/nix-config/nix-coding

my-module/
  interface.nix        # options only
  default.nix          # imports + orchestration
  feature-a.nix        # config for feature A
  feature-b.nix        # config for feature B

{ lib, config, ... }:
{
  imports = [
    ./interface.nix
    ./feature-a.nix
    ./feature-b.nix
  ];
  config._module.args.my-lib = import ./lib { inherit lib; };
}

{ config, lib, pkgs, ... }:
let
  inherit (lib) mkIf mkEnableOption mkOption types;
  cfg = config.my.module;
in
{
  options.my.module = {
    enable = mkEnableOption "my module";
    package = mkOption {
      type = types.package;
      default = pkgs.my-package;
      description = "Package to use.";
    };
  };
 
  config = mkIf cfg.enable {
    # ...
  };
}

enable = (lib.mkEnableOption "my feature") // { default = true; };

config.my.option = lib.mkIf condition (lib.mkDefault computedValue);

config.github-actions = lib.mkMerge [
  { runs-on = "ubuntu-latest"; steps = baseSteps; }
  (lib.mkIf cfg.checkout { steps = lib.mkBefore [{ uses = "actions/checkout@v4"; }]; })
  (lib.mkIf (cfg.env != { }) { env = cfg.env; })
];

jobs = lib.mkOption {
  type = lib.types.listOf lib.types.str;
  apply = lib.unique;  # deduplicate automatically
};
 
needs = lib.mkOption {
  apply = lib.pipe [
    lib.flatten
    lib.unique
    (builtins.filter (n: n != config.name))  # remove self-references
  ];
};

# lazyAttrsOf — prefer over attrsOf for submodule attrsets
jobs = lib.mkOption {
  type = lib.types.lazyAttrsOf (lib.types.submoduleWith { modules = [ ./job ]; });
};
 
# functionTo — expose a configurable transform
formatName = lib.mkOption {
  type = lib.types.functionTo lib.types.str;
  default = lib.concatStringsSep "-";
};
 
# shorthandOnlyDefinesConfig — let callers use bare attrsets
type = lib.types.submoduleWith {
  modules = [ ./item ];
  shorthandOnlyDefinesConfig = true;
};

# In the root module:
config._module.args.my-lib = import ./lib { inherit lib; };
 
# In any submodule:
{ my-lib, config, lib, ... }: {
  config.result = my-lib.transform config.value;
}

config._module.freeformType = lib.types.attrsOf lib.types.anything;

_computed = lib.mkOption {
  internal = true;
  type = lib.types.package;
  default = lib.pipe config.documents [ … ];
};

type = lib.types.submoduleWith {
  modules = [ ./child ];
  specialArgs.parentConfig = config;  # accessible as a function arg in child
};

type = types.submodule {
  options = {
    foo = mkOption { type = types.str; };
  };
};

# Conditional list elements
lib.optionals condition [ "a" "b" ]
lib.optional condition "a"
 
# Conditional attrset assembly — prefer over chained // operators
lib.mergeAttrsList [
  { always = "present"; }
  (lib.optionalAttrs condition { extra = "field"; })
  (lib.optionalAttrs other { another = "field"; })
]
 
# attrset manipulation
lib.filterAttrs (k: v: v != null) attrs
lib.mapAttrs (k: v: transform v) attrs
lib.mapAttrsToList (k: v: "${k}=${v}") attrs
lib.genAttrs [ "a" "b" ] (name: "value-${name}")
 
# List operations
lib.concatMap f list     # map then flatten one level
lib.unique list          # deduplicate
lib.flatten list         # flatten arbitrarily nested list
 
# String operations
lib.concatStringsSep ", " list
lib.concatMapStringsSep "\n" f list
lib.replaceStrings [ "old" ] [ "new" ] str
 
# Path helpers
lib.escapeShellArg str
lib.getExe pkg  # shorthand for "${pkg}/bin/${lib.getName pkg}"

, nixfmt file.nix        # format in place
, nixfmt < input.nix     # format from stdin

, deadnix -e file.nix    # edit in place, removing dead code
, deadnix file.nix       # check only, print dead code

, statix check file.nix  # report antipatterns
, statix fix file.nix    # auto-fix antipatterns where possible