feat(plugin): added Plugin.priority for start plugins

Author: folke

README.md

@@ -103,6 +103,7 @@ require("lazy").setup({
 | **ft**           | `string?` or `string[]`                                   | Lazy-load on filetype                                                                                                                                                                                                                  |
 | **keys**         | `string?` or `string[]` or `LazyKeys[]`                   | Lazy-load on key mapping                                                                                                                                                                                                               |
 | **module**       | `false?`                                                  | Do not automatically load this Lua module when it's required somewhere                                                                                                                                                                 |
+| **priority**     | `number?`                                                 | Only useful for **start** plugins (`lazy=false`) to force loading certain plugins first. Default priority is `50`. It's recommended to set this to a high number for colorschemes.                                                     |
 
 ### Lazy Loading
 
@@ -114,9 +115,6 @@ module of plugin `A`, then plugin `A` will be loaded on demand as expected.
 If you don't want this behavior for a certain plugin, you can specify that with `module=false`.
 You can then manually load the plugin with `:Lazy load foobar.nvim`.
 
-Colorscheme plugins can be configured with `lazy=true`. The plugin will automagically load
-when doing `colorscheme foobar`.
-
 You can configure **lazy.nvim** to lazy-load all plugins by default with `config.defaults.lazy = true`.
 
 Additionally, you can also lazy-load on **events**, **commands**,
@@ -128,6 +126,15 @@ Plugins will be lazy-loaded when one of the following is `true`:
 - it has an `event`, `cmd`, `ft` or `keys` key
 - `config.defaults.lazy == true`
 
+#### 🌈 Colorschemes
+
+Colorscheme plugins can be configured with `lazy=true`. The plugin will automagically load
+when doing `colorscheme foobar`.
+
+> **NOTE:** since **start** plugins can possibly change existing highlight groups,
+> it's important to make sure that your main **colorscheme** is loaded first.
+> To ensure this you can use the `priority=1000` field. **_(see the examples)_**
+
 #### ⌨️ Lazy Key Mappings
 
 The `keys` property can be a `string` or `string[]` for simple normal-mode mappings, or it
@@ -186,7 +193,15 @@ version of plugins that support Semver.
 ```lua
 return {
   -- the colorscheme should be available when starting Neovim
-  "folke/tokyonight.nvim",
+  {
+    "folke/tokyonight.nvim",
+    lazy = false, -- make sure we load this during startup if it is your main colorscheme
+    priority = 1000, -- make sure to load this before all the other start plugins
+    config = function()
+      -- load the colorscheme here
+      vim.cmd([[colorscheme tokyonight]])
+    end,
+  },
 
   -- I have a separate config.mappings file where I require which-key.
   -- With lazy the plugin will be automatically loaded when it is required somewhere

lua/lazy/core/loader.lua

@@ -4,6 +4,8 @@ local Handler = require("lazy.core.handler")
 
 local M = {}
 
+local DEFAULT_PRIORITY = 50
+
 ---@type LazyPlugin[]
 M.loading = {}
 M.init_done = false
@@ -73,8 +75,9 @@ function M.startup()
 
   -- 2. load start plugin
   Util.track({ start = "start" })
-  for _, plugin in pairs(Config.plugins) do
-    if plugin.lazy == false and not plugin._.loaded then
+  for _, plugin in ipairs(M.get_start_plugins()) do
+    -- plugin may be loaded by another plugin in the meantime
+    if not plugin._.loaded then
       M.load(plugin, { start = "start" })
     end
   end
@@ -103,6 +106,22 @@ function M.startup()
   Util.track()
 end
 
+function M.get_start_plugins()
+  ---@type LazyPlugin[]
+  local start = {}
+  for _, plugin in pairs(Config.plugins) do
+    if plugin.lazy == false and not plugin._.loaded then
+      start[#start + 1] = plugin
+    end
+  end
+  table.sort(start, function(a, b)
+    local ap = a.priority or DEFAULT_PRIORITY
+    local bp = b.priority or DEFAULT_PRIORITY
+    return ap > bp
+  end)
+  return start
+end
+
 ---@class Loader
 ---@param plugins string|LazyPlugin|string[]|LazyPlugin[]
 ---@param reason {[string]:string}

lua/lazy/example.lua

@@ -1,6 +1,14 @@
 return {
   -- the colorscheme should be available when starting Neovim
-  "folke/tokyonight.nvim",
+  {
+    "folke/tokyonight.nvim",
+    lazy = false, -- make sure we load this during startup if it is your main colorscheme
+    priority = 1000, -- make sure to load this before all the other start plugins
+    config = function()
+      -- load the colorscheme here
+      vim.cmd([[colorscheme tokyonight]])
+    end,
+  },
 
   -- I have a separate config.mappings file where I require which-key.
   -- With lazy the plugin will be automatically loaded when it is required somewhere

lua/lazy/types.lua

@@ -41,6 +41,7 @@
 ---@field enabled? boolean|(fun():boolean)
 ---@field cond? boolean|(fun():boolean)
 ---@field lazy? boolean
+---@field priority? number Only useful for lazy=false plugins to force loading certain plugins first. Default priority is 50
 ---@field dev? boolean If set, then link to the respective folder under your ~/projects
 
 ---@class LazyPlugin: LazyPluginBase,LazyPluginHandlers,LazyPluginHooks,LazyPluginRef