wrappers: expose platform wrapper modules via build.*Module options

Expose the platform wrapper modules as the Nixvim configuration options
`build.nixosModule`, `build.homeModule`, and `build.nixDarwinModule`.
This makes it possible to reuse a single Nixvim configuration across
NixOS, Home Manager, and nix-darwin without re-importing modules into
`programs.nixvim` manually.

Evaluating these wrapper modules requires a "bare" Nixvim configuration;
one that does not define `pkgs` or `nixpkgs.hostPlatform`. Such a
configuration would normally fail to evaluate, but disabling
`_module.check` provides a sufficiently lazy evaluation to access the
wrapper options.

To prevent the `_module.check = false` module from leaking into user
configs, it has a unique module key and gets disabled inside the wrapper
modules (`wrappers/_shared.nix`).

Author: MattSturgeon

flake/wrappers.nix

@@ -4,10 +4,26 @@
   ...
 }:
 let
-  inherit (lib.modules) importApply;
   # Added 2025-05-25; warning shown since 2025-08-01 (25.11)
   # NOTE: top-level binding of a fully resolved value, to avoid printing multiple times
   homeManagerModulesWarning = lib.warn "nixvim: flake output `homeManagerModules` has been renamed to `homeModules`." null;
+
+  # A base configuration used to evaluate the wrapper modules.
+  #
+  # While we don't define a `pkgs` or `hostPlatform` here, which would normally
+  # lead to eval errors, disabling option-declaration checking gives us enough
+  # laziness to evaluate the options we need.
+  #
+  # The `_module.check` module has a key, so we can disable it later in the
+  # platform wrapper modules.
+  configuration = self.lib.evalNixvim {
+    modules = [
+      {
+        key = "<internal:nixvim-nocheck-base-eval>";
+        config._module.check = false;
+      }
+    ];
+  };
 in
 {
   perSystem =
@@ -27,17 +43,17 @@ in
 
   flake = {
     nixosModules = {
-      nixvim = importApply ../wrappers/nixos.nix self;
+      nixvim = configuration.config.build.nixosModule;
       default = self.nixosModules.nixvim;
     };
     # Alias for backward compatibility
     homeManagerModules = lib.mapAttrs (_: lib.seq homeManagerModulesWarning) self.homeModules;
     homeModules = {
-      nixvim = importApply ../wrappers/hm.nix self;
+      nixvim = configuration.config.build.homeModule;
       default = self.homeModules.nixvim;
     };
     nixDarwinModules = {
-      nixvim = importApply ../wrappers/darwin.nix self;
+      nixvim = configuration.config.build.nixDarwinModule;
       default = self.nixDarwinModules.nixvim;
     };
   };

modules/default.nix

@@ -24,5 +24,6 @@
     ./output.nix
     ./performance.nix
     ./plugins.nix
+    ./wrappers.nix
   ];
 }

modules/wrappers.nix

@@ -0,0 +1,40 @@
+{
+  lib,
+  extendModules,
+  config,
+  ...
+}:
+{
+  options.build = {
+    nixosModule = lib.mkOption {
+      type = lib.types.deferredModule;
+      description = "A NixOS module that installs this Nixvim configuration.";
+      readOnly = true;
+    };
+    homeModule = lib.mkOption {
+      type = lib.types.deferredModule;
+      description = "A Home Manager module that installs this Nixvim configuration.";
+      readOnly = true;
+    };
+    nixDarwinModule = lib.mkOption {
+      type = lib.types.deferredModule;
+      description = "A nix-darwin module that installs this Nixvim configuration.";
+      readOnly = true;
+    };
+  };
+
+  config.build = {
+    nixosModule = lib.modules.importApply ../wrappers/nixos.nix {
+      self = config.flake;
+      inherit extendModules;
+    };
+    homeModule = lib.modules.importApply ../wrappers/hm.nix {
+      self = config.flake;
+      inherit extendModules;
+    };
+    nixDarwinModule = lib.modules.importApply ../wrappers/darwin.nix {
+      self = config.flake;
+      inherit extendModules;
+    };
+  };
+}

wrappers/_shared.nix

@@ -1,8 +1,8 @@
 {
   # The nixvim flake
   self,
-  # Extra args for the `evalNixvim` call that produces the type for `programs.nixvim`
-  evalArgs ? { },
+  # Function used to evaluate the `programs.nixvim` configuration
+  extendModules,
   # Option path where extraFiles should go
   filesOpt ? null,
   # Filepath prefix to apply to extraFiles
@@ -45,14 +45,11 @@ let
       };
     };
 
-  nixvimConfiguration = config.lib.nixvim.modules.evalNixvim (
-    evalArgs
-    // {
-      modules = evalArgs.modules or [ ] ++ [
-        nixpkgsModule
-      ];
-    }
-  );
+  nixvimConfiguration = extendModules {
+    modules = [ nixpkgsModule ];
+    disabledModules = [ "<internal:nixvim-nocheck-base-eval>" ];
+  };
+
   extraFiles = lib.filter (file: file.enable) (lib.attrValues cfg.extraFiles);
 in
 {

wrappers/darwin.nix

@@ -1,4 +1,7 @@
-self:
+{
+  self,
+  extendModules,
+}:
 {
   config,
   lib,
@@ -12,19 +15,22 @@ let
     importApply
     ;
   cfg = config.programs.nixvim;
-  evalArgs = {
-    extraSpecialArgs = {
-      darwinConfig = config;
-    };
-    modules = [
-      ./modules/darwin.nix
-    ];
-  };
 in
 {
   _file = ./darwin.nix;
 
-  imports = [ (importApply ./_shared.nix { inherit self evalArgs; }) ];
+  imports = [
+    (importApply ./_shared.nix {
+      inherit self;
+      inherit
+        (extendModules {
+          specialArgs.darwinConfig = config;
+          modules = [ ./modules/darwin.nix ];
+        })
+        extendModules
+        ;
+    })
+  ];
 
   config = mkIf cfg.enable {
     environment.systemPackages = [

wrappers/hm.nix

@@ -1,4 +1,7 @@
-self:
+{
+  self,
+  extendModules,
+}:
 {
   config,
   lib,
@@ -9,21 +12,20 @@ let
     mkIf
     ;
   cfg = config.programs.nixvim;
-  evalArgs = {
-    extraSpecialArgs = {
-      hmConfig = config;
-    };
-    modules = [
-      ./modules/hm.nix
-    ];
-  };
 in
 {
   _file = ./hm.nix;
 
   imports = [
     (import ./_shared.nix {
-      inherit self evalArgs;
+      inherit self;
+      inherit
+        (extendModules {
+          specialArgs.hmConfig = config;
+          modules = [ ./modules/hm.nix ];
+        })
+        extendModules
+        ;
       filesOpt = [
         "xdg"
         "configFile"

wrappers/nixos.nix

@@ -1,4 +1,7 @@
-self:
+{
+  self,
+  extendModules,
+}:
 {
   config,
   lib,
@@ -9,21 +12,20 @@ let
     mkIf
     ;
   cfg = config.programs.nixvim;
-  evalArgs = {
-    extraSpecialArgs = {
-      nixosConfig = config;
-    };
-    modules = [
-      ./modules/nixos.nix
-    ];
-  };
 in
 {
   _file = ./nixos.nix;
 
   imports = [
     (import ./_shared.nix {
-      inherit self evalArgs;
+      inherit self;
+      inherit
+        (extendModules {
+          specialArgs.nixosConfig = config;
+          modules = [ ./modules/nixos.nix ];
+        })
+        extendModules
+        ;
       filesOpt = [
         "environment"
         "etc"