Skip to content

docs: clarify custom plugin load ordering #2151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TyceHerrman wants to merge 1 commit into
base: master
Choose a base branch
from
+13 −3
Open

docs: clarify custom plugin load ordering #2151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions init.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -976,10 +976,19 @@ do
-- require 'kickstart.plugins.neo-tree'
-- require 'kickstart.plugins.gitsigns' -- adds gitsigns recommended keymaps

-- NOTE: You can add your own plugins, configuration, etc from `lua/custom/plugins/*.lua`
-- NOTE: You can add your own plugins, configuration, etc. in `lua/custom/plugins/*.lua`.
--
-- Uncomment the following line and add your plugins to `lua/custom/plugins/*.lua` to get going.
-- For independent modules, uncomment the convenience loader:
-- require 'custom.plugins'
--
-- `custom.plugins` automatically loads files from that directory, but their

@Christoph-Raab Christoph-Raab Aug 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe out of scope for the PR, but why doesn't the repo recommand using the official after/plugin way? That would be more nvim native and would save a bit of complexity with the custom init.lua in lua/custom/plugins.

@TyceHerrman TyceHerrman Aug 26, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that could be a better approach, but it's a bigger change. files under after/plugin/ run in a later startup phase. During init.lua, vim.pack.add() defaults to load = false, and after init.lua it defaults to load = true. Moving the current vim.pack.add() and setup() calls into after/plugin/ would change when plugin scripts are loaded. This PR documents how the existing loader works, but Kickstart adopting after/plugin/ as its recommended extension layout would supersede it. so could be closed if that's the direction to go now, but if that needs further deliberation, could merge this PR as is imho

-- order is unspecified. If plugins depend on each other, keep them in the same
-- file and put their `vim.pack.add()` and `setup()` calls in the required order.
--
-- If separate modules need a specific order, require them explicitly instead:
-- require 'custom.plugins.colorscheme'
-- require 'custom.plugins.ui'
-- require 'custom.plugins.git'
end

-- The line beneath this is called `modeline`. See `:help modeline`
Expand Down
3 changes: 2 additions & 1 deletion lua/custom/plugins/init.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
--
-- See the kickstart.nvim README for more information

-- Iterate over all Lua files in the plugins directory and load them
-- Iterate over all Lua files in the plugins directory and load them.
-- `vim.fs.dir()` iteration order is unspecified and must not be relied upon.
local plugins_dir = vim.fs.joinpath(vim.fn.stdpath 'config', 'lua', 'custom', 'plugins')
for file_name, type in vim.fs.dir(plugins_dir, { follow = true }) do
if (type == 'file' or type == 'link') and file_name:match '%.lua$' and file_name ~= 'init.lua' then
Expand Down