modules/nixpkgs: init useGlobalPackages option

wrappers/_shared.nix

@@ -28,18 +28,30 @@ let
     setAttrByPath
     ;
   cfg = config.programs.nixvim;
-  nixvimConfiguration = config.lib.nixvim.modules.evalNixvim (
-    evalArgs
-    // {
-      modules = evalArgs.modules or [ ] ++ [
-        {
-          _file = ./_shared.nix;
 
-          nixpkgs = {
-            # Use global packages by default in nixvim's submodule
-            # TODO: `useGlobalPackages` option and/or deprecate using host packages?
-            pkgs = lib.mkDefault pkgs;
+  # TODO: Find a way to document the options declared here
+  nixpkgsModule =
+    { config, ... }:
+    {
+      _file = ./_shared.nix;
+
+      options.nixpkgs = {
+        useGlobalPackages = lib.mkOption {
+          type = lib.types.bool;
+          default = true; # TODO: Added 2024-10-20; switch to false one release after adding a deprecation warning
+          description = ''
+            Whether Nixvim should use the host configuration's `pkgs` instance.
+
+            The host configuration is usually home-manager, nixos, or nix-darwin.
 
+            When false, an instance of nixpkgs will be constructed by nixvim.
+          '';
+        };
+      };
+
+      config = {
+        nixpkgs =
+          {
             # TODO: Handle this in evalNixvim
             source = lib.mkOptionDefault self.inputs.nixpkgs;
 
@@ -48,8 +60,18 @@ let
             #        (it defaults to hostPlatform)...
             hostPlatform = lib.mkOptionDefault pkgs.stdenv.hostPlatform;
             buildPlatform = lib.mkDefault pkgs.stdenv.buildPlatform;
+          }
+          # Use global packages by default in nixvim's submodule
+          // lib.optionalAttrs config.nixpkgs.useGlobalPackages {
+            pkgs = lib.mkForce pkgs;
           };
-        }
+      };
+    };
+  nixvimConfiguration = config.lib.nixvim.modules.evalNixvim (
+    evalArgs
+    // {
+      modules = evalArgs.modules or [ ] ++ [
+        nixpkgsModule
       ];
     }
   );