mkNeovimPlugin: add lazyLoad with lz-n support

lib/default.nix

@@ -66,6 +66,7 @@ lib.fix (
       defaultNullOpts
       mkCompositeOption
       mkCompositeOption'
+      mkLazyLoadOption
       mkNullOrLua
       mkNullOrLua'
       mkNullOrLuaFn

lib/neovim-plugin.nix

@@ -89,6 +89,7 @@
           options.${namespace}.${name} =
             {
               enable = lib.mkEnableOption originalName;
+              lazyLoad = lib.nixvim.mkLazyLoadOption originalName;
               package =
                 if lib.isOption package then
                   package
@@ -161,8 +162,39 @@
                   # Add the plugin setup code `require('foo').setup(...)` to the lua configuration
                   (lib.optionalAttrs callSetup { ${namespace}.${name}.luaConfig.content = setupCode; })
 
-                  # Write the lua configuration `luaConfig.content` to the config file
-                  (setLuaConfig cfg.luaConfig.content)
+                  # Write the lua configuration `luaConfig.content` to the config file when lazy loading is not enabled
+                  (lib.mkIf (!cfg.lazyLoad.enable) (setLuaConfig cfg.luaConfig.content))
+
+                  # When lazy loading is enabled for this plugin, route its configuration to the enabled provider
+                  (lib.mkIf cfg.lazyLoad.enable {
+                    assertions = [
+                      {
+                        assertion = (isColorscheme && colorscheme != null) || cfg.lazyLoad.settings != { };
+                        message = "You have enabled lazy loading for ${originalName} but have not provided any configuration.";
+                      }
+                    ];
+                    plugins.lz-n = {
+                      plugins = [
+                        (
+                          {
+                            __unkeyed-1 = originalName;
+                            # Use provided after, otherwise fallback to normal function wrapped lua content
+                            after =
+                              let
+                                after = cfg.lazyLoad.settings.after or null;
+                                default = "function()\n " + cfg.luaConfig.content + " \nend";
+                              in
+                              if (lib.isString after || lib.types.rawLua.check after) then after else default;
+                            colorscheme = lib.mkIf isColorscheme (cfg.lazyLoad.settings.colorscheme or colorscheme);
+                          }
+                          // lib.removeAttrs cfg.lazyLoad.settings [
+                            "after"
+                            "colorscheme"
+                          ]
+                        )
+                      ];
+                    };
+                  })
                 ])
               )
             );

lib/options.nix

@@ -333,5 +333,53 @@ rec {
         else
           example;
     };
+
+  mkLazyLoadOption =
+    originalName:
+    lib.mkOption {
+      description = ''
+        Lazy-load settings for ${originalName}.
+
+        > [!WARNING]
+        > This is an experimental option and may not work as expected with all plugins.
+        > The API may change without notice.
+        > Please report any issues you encounter.
+      '';
+      default = { };
+      type = types.submodule (
+        { config, ... }:
+        {
+          options = {
+            enable = lib.mkOption {
+              default = lib.any (x: x != null) (builtins.attrValues config.settings);
+              defaultText = lib.literalMD ''
+                `true` when `settings` has a non-null attribute
+              '';
+              description = ''
+                lazy-loading for ${originalName}
+              '';
+            };
+
+            settings = lib.nixvim.mkSettingsOption {
+              description = ''
+                Lazy provider configuration settings.
+
+                Check your lazy loading provider's documentation on settings to configure.
+              '';
+              example = {
+                cmd = "Neotest";
+                keys = [
+                  {
+                    __unkeyed-1 = "<leader>nt";
+                    __unkeyed-3 = "<CMD>Neotest summary<CR>";
+                    desc = "Summary toggle";
+                  }
+                ];
+              };
+            };
+          };
+        }
+      );
+    };
 }
 // removed

modules/lazyload.nix

@@ -26,5 +26,33 @@ in
           '';
         }
       ];
+    warnings =
+      let
+        ignoredPackages = [
+          # removed
+          "treesitter-playground"
+          # renamed
+          "surround"
+          "null-ls"
+          "wilder-nvim"
+        ];
+
+        pluginsWithLazyLoad = builtins.filter (
+          x:
+          !(lib.elem x ignoredPackages)
+          && lib.hasAttr "lazyLoad" config.plugins.${x}
+          && config.plugins.${x}.lazyLoad.enable
+        ) (builtins.attrNames config.plugins);
+        count = builtins.length pluginsWithLazyLoad;
+      in
+      lib.optionals (count > 0 && !config.plugins.lz-n.enable) [
+        ''
+          You have enabled lazy loading support for the following plugins but have not enabled a lazy loading provider.
+            ${lib.concatImapStringsSep "\n" (i: x: "${toString i}. plugins.${x}") pluginsWithLazyLoad}
+
+          Currently supported lazy providers:
+            - lz-n
+        ''
+      ];
   };
 }

plugins/by-name/typescript-tools/default.nix

@@ -221,6 +221,7 @@ lib.nixvim.neovim-plugin.mkNeovimPlugin {
       ];
     in
     {
+      # TODO: handle lazy loading properly
       plugins.lsp.postConfig =
         let
           # TODO:: introduced 10-22-2024: remove after 24.11