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

Author: folke

README.md

@@ -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
-        if opts == true then
+        local opts = M.opts(plugin)
+        if next(opts) == nil then
           opts = nil
         end
         require(mods[1]).setup(opts)

lua/lazy/core/loader.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/core/plugin.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/example.lua

@@ -68,38 +68,44 @@ 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
 end
 
 M.valid = {
   1,
-  "name",
-  "url",
-  "enabled",
-  "lazy",
-  "dev",
-  "dependencies",
-  "init",
-  "config",
-  "build",
+  "_",
   "branch",
-  "tag",
-  "commit",
-  "version",
-  "module",
-  "pin",
+  "build",
   "cmd",
+  "commit",
+  "cond",
+  "config",
+  "dependencies",
+  "dev",
+  "dir",
+  "enabled",
   "event",
-  "keys",
   "ft",
-  "dir",
+  "import",
+  "init",
+  "keys",
+  "lazy",
+  "module",
+  "name",
+  "opts",
+  "pin",
   "priority",
-  "cond",
-  "_",
+  "tag",
+  "url",
+  "version",
 }
 
 return M

lua/lazy/health.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 config? fun(LazyPlugin)|true|table Will be executed when loading the plugin
----@field build? string|fun(LazyPlugin)|(string|fun(LazyPlugin))[]
+---@field init? fun(self:LazyPlugin) Will always be run
+---@field config? fun(self:LazyPlugin, opts:table)|true Will be executed when loading the plugin
+---@field build? string|fun(self:LazyPlugin)|(string|fun(self:LazyPlugin))[]
+---@field opts? PluginOpts
 
 ---@class LazyPluginHandlers
 ---@field event? string[]

lua/lazy/types.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)