feat(spec)!: setting a table to `Plugin.config` is now deprecated. Please use `Plugin.opts` instead. (backward compatible for now)

README.md

@@ -80,7 +80,7 @@ require("lazy").setup({
 ## 🔌 Plugin Spec
 
 | Property         | Type                                                      | Description                                                                                                                                                                                                                               |
-| ---------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ---------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `[1]`            | `string?`                                                 | Short plugin url. Will be expanded using `config.git.url_format`                                                                                                                                                                          |
 | **dir**          | `string?`                                                 | A directory pointing to a local plugin                                                                                                                                                                                                    |
 | **url**          | `string?`                                                 | A custom git url where the plugin is hosted                                                                                                                                                                                               |
@@ -91,7 +91,8 @@ require("lazy").setup({
 | **cond**         | `boolean?` or `fun():boolean`                             | When `false`, or if the `function` returns false, then this plugin will not be loaded. Useful to disable some plugins in vscode, or firenvim for example.                                                                                 |
 | **dependencies** | `LazySpec[]`                                              | A list of plugin names or plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise. When specifying a name, make sure the plugin spec has been defined somewhere else.    |
 | **init**         | `fun(LazyPlugin)`                                         | `init` functions are always executed during startup                                                                                                                                                                                       |
-| **config**       | `fun(LazyPlugin)` or `true` or `table`                    | `config` is executed when the plugin loads. You can also set to `true` or pass a `table`, that will be passed to `require("plugin").setup(opts)`                                                                                       |
+| **config**       | `fun(LazyPlugin, opts:table)` or `true`                   | `config` is executed when the plugin loads. You can also set it to `true`, to automatically run `require("plugin").setup(opts)`. See also `opts`.                                                                                         |
+| **opts**         | `table` or `fun(LazyPlugin, opts:table)`                  | `opts` should be a table (will be merged with parent specs), return a table (replaces parent specs) or should change a table. The table will be passed to the `Plugin.config()` function. Setting this value will imply `Plugin.config()` |
 | **build**        | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. If it's a string it will be ran as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands             |
 | **branch**       | `string?`                                                 | Branch of the repository                                                                                                                                                                                                                  |
 | **tag**          | `string?`                                                 | Tag of the repository                                                                                                                                                                                                                     |
@@ -224,11 +225,11 @@ return {
     config = true, -- run require("neorg").setup()
   },
 
-  -- or set a custom config:
+  -- or set custom options:
   {
     "nvim-neorg/neorg",
     ft = "norg",
-    config = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"})
+    opts = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"})
   },
 
   {
@@ -660,6 +661,24 @@ For a real-life example, you can check [LazyVim](https://github.com/LazyVim/Lazy
 
 - [lazyvim.plugins](https://github.com/LazyVim/LazyVim/tree/main/lua/lazyvim/plugins) contains all the plugin specs that will be loaded
 
+### ↩️ Importing Specs, `config` & `opts`
+
+As part of a spec, you can add `import` statements to import additional plugin modules.
+Both of the `setup()` calls are equivalent:
+
+```lua
+require("lazy").setup("plugins")
+
+-- same as:
+require("lazy").setup({{import = "plugins"}})
+```
+
+When you import specs, you can override them by simply adding a spec for the same plugin to your local
+specs, adding any keys you want to override / merge.
+
+`opts`, `dependencies`, `cmd`, `event`, `ft` and `keys` are always merged with the parent spec.
+Any other property will override the property from the parent spec.
+
 ## 📦 Migration Guide
 
 ### [packer.nvim](https://github.com/wbthomason/packer.nvim)

lua/lazy/core/loader.lua

@@ -220,7 +220,7 @@ function M._load(plugin, reason, opts)
   end
 
   M.packadd(plugin.dir)
-  if plugin.config then
+  if plugin.config or plugin.opts then
     M.config(plugin)
   end
 
@@ -231,13 +231,32 @@ function M._load(plugin, reason, opts)
   end)
 end
 
+-- Merges super opts or runs the opts function to override opts or return new ones
+---@param plugin LazyPlugin
+function M.opts(plugin)
+  local opts = plugin._.super and M.opts(plugin._.super) or {}
+  ---@type PluginOpts?
+  local plugin_opts = rawget(plugin, "opts")
+
+  if type(plugin_opts) == "table" then
+    opts = Util.merge(opts, plugin_opts)
+  elseif type(plugin_opts) == "function" then
+    local new_opts = plugin_opts(plugin, opts)
+    if new_opts then
+      opts = new_opts
+    end
+  end
+
+  return opts
+end
+
 --- runs plugin config
 ---@param plugin LazyPlugin
 function M.config(plugin)
   local fn
   if type(plugin.config) == "function" then
     fn = function()
-      plugin.config(plugin)
+      plugin.config(plugin, M.opts(plugin))
     end
   else
     local normname = Util.normname(plugin.name)
@@ -254,8 +273,8 @@ function M.config(plugin)
     end
     if #mods == 1 then
       fn = function()
-        local opts = plugin.config
+        local opts = M.opts(plugin)
-        if opts == true then
+        if next(opts) == nil then
           opts = nil
         end
         require(mods[1]).setup(opts)

lua/lazy/core/plugin.lua

@@ -87,6 +87,15 @@ function Spec:add(plugin, results, is_dep)
   plugin.cmd = type(plugin.cmd) == "string" and { plugin.cmd } or plugin.cmd
   plugin.ft = type(plugin.ft) == "string" and { plugin.ft } or plugin.ft
 
+  if type(plugin.config) == "table" then
+    self:warn(
+      "{" .. plugin.name .. "}: setting a table to `Plugin.config` is deprecated. Please use `Plugin.opts` instead"
+    )
+    ---@diagnostic disable-next-line: assign-type-mismatch
+    plugin.opts = plugin.config
+    plugin.config = nil
+  end
+
   plugin._ = {}
   plugin._.dep = is_dep
 

lua/lazy/example.lua

@@ -31,11 +31,11 @@ return {
     config = true, -- run require("neorg").setup()
   },
 
-  -- or set a custom config:
+  -- or set custom options:
   {
     "nvim-neorg/neorg",
     ft = "norg",
-    config = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"})
+    opts = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"})
   },
 
   {

lua/lazy/health.lua

@@ -68,8 +68,12 @@ function M.check_override(plugin)
     return
   end
 
+  local Handler = require("lazy.core.handler")
+  local skip = { "dependencies", "_", "opts" }
+  vim.list_extend(skip, vim.tbl_values(Handler.types))
+
   for key, value in pairs(plugin._.super) do
-    if key ~= "_" and plugin[key] and plugin[key] ~= value then
+    if not vim.tbl_contains(skip, key) and plugin[key] and plugin[key] ~= value then
       vim.health.report_warn("{" .. plugin.name .. "}: overriding <" .. key .. ">")
     end
   end
@@ -77,29 +81,31 @@ end
 
 M.valid = {
   1,
-  "name",
-  "url",
-  "enabled",
-  "lazy",
-  "dev",
-  "dependencies",
-  "init",
-  "config",
-  "build",
-  "branch",
-  "tag",
-  "commit",
-  "version",
-  "module",
-  "pin",
-  "cmd",
-  "event",
-  "keys",
-  "ft",
-  "dir",
-  "priority",
-  "cond",
   "_",
+  "branch",
+  "build",
+  "cmd",
+  "commit",
+  "cond",
+  "config",
+  "dependencies",
+  "dev",
+  "dir",
+  "enabled",
+  "event",
+  "ft",
+  "import",
+  "init",
+  "keys",
+  "lazy",
+  "module",
+  "name",
+  "opts",
+  "pin",
+  "priority",
+  "tag",
+  "url",
+  "version",
 }
 
 return M

lua/lazy/types.lua

@@ -15,10 +15,13 @@
 ---@field cond? boolean
 ---@field super? LazyPlugin
 
+---@alias PluginOpts table|fun(self:LazyPlugin, opts:table):table?
+
 ---@class LazyPluginHooks
----@field init? fun(LazyPlugin) Will always be run
+---@field init? fun(self:LazyPlugin) Will always be run
----@field config? fun(LazyPlugin)|true|table Will be executed when loading the plugin
+---@field config? fun(self:LazyPlugin, opts:table)|true Will be executed when loading the plugin
----@field build? string|fun(LazyPlugin)|(string|fun(LazyPlugin))[]
+---@field build? string|fun(self:LazyPlugin)|(string|fun(self:LazyPlugin))[]
+---@field opts? PluginOpts
 
 ---@class LazyPluginHandlers
 ---@field event? string[]

tests/core/plugin_spec.lua

@@ -1,5 +1,6 @@
 local Config = require("lazy.core.config")
 local Plugin = require("lazy.core.plugin")
+local Loader = require("lazy.core.loader")
 
 local assert = require("luassert")
 
@@ -272,3 +273,37 @@ describe("plugin spec opt", function()
     end
   end)
 end)
+
+describe("plugin opts", function()
+  it("correctly parses opts", function()
+    ---@type {spec:LazySpec, opts:table}[]
+    local tests = {
+      {
+        spec = { { "foo/foo", opts = { a = 1, b = 1 } }, { "foo/foo", opts = { a = 2 } } },
+        opts = { a = 2, b = 1 },
+      },
+      {
+        spec = { { "foo/foo", config = { a = 1, b = 1 } }, { "foo/foo", opts = { a = 2 } } },
+        opts = { a = 2, b = 1 },
+      },
+      {
+        spec = { { "foo/foo", opts = { a = 1, b = 1 } }, { "foo/foo", config = { a = 2 } } },
+        opts = { a = 2, b = 1 },
+      },
+      {
+        spec = { { "foo/foo", config = { a = 1, b = 1 } }, { "foo/foo", config = { a = 2 } } },
+        opts = { a = 2, b = 1 },
+      },
+      {
+        spec = { { "foo/foo", config = { a = 1, b = 1 } }, { "foo/foo", config = { a = vim.NIL } } },
+        opts = { b = 1 },
+      },
+    }
+
+    for _, test in ipairs(tests) do
+      local spec = Plugin.Spec.new(test.spec)
+      assert(spec.plugins.foo)
+      assert.same(test.opts, Loader.opts(spec.plugins.foo))
+    end
+  end)
+end)