mirror of https://github.com/folke/lazy.nvim.git
f25f942eb7 | ||
---|---|---|
.github | ||
doc | ||
lua/lazy | ||
tests | ||
.gitignore | ||
.neoconf.json | ||
CHANGELOG.md | ||
README.md | ||
TODO.md | ||
selene.toml | ||
stylua.toml | ||
vim.toml |
README.md
💤 lazy.nvim
lazy.nvim is a modern plugin manager for Neovim.
✨ Features
- 📦 Manage all your Neovim plugins with a sleek and intuitive UI
- 🚀 Fast startup times thanks to automatic caching and bytecode compilation of lua modules.
- 💾 Partial clones instead of shallow clones
- 🔌 Automatic lazy-loading of lua modules and lazy-loading on events, commands, filetypes, and key mappings.
- ⏳ Automatically install missing plugins before starting up Neovim, allowing you to start using it right away.
- 💪 Async execution for improved performance
- 🛠️ No need to manually compile plugins
- 🧪 Correct sequencing of dependencies
- 📁 Configurable in multiple files
- 📚 Generates helptags of the headings in
README.md
files for plugins that don't have vimdocs - 💻 Dev options and patterns for using local plugins
- 📊 Profiling tools to optimize performance
- 🔒 Lockfile
lazy-lock.json
to keep track of installed plugins - 🔎 Automatically check for updates
- 📋 Commit, branch, tag, version, and full Semver support
- 📈 Statusline component to see the number of pending updates
⚡️ Requirements
- Neovim >= 0.8.0
📦 Installation
You can use the following Lua code to bootstrap lazy.nvim
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
vim.fn.system({
"git",
"clone",
"--filter=blob:none",
"--single-branch",
"git@github.com:folke/lazy.nvim.git",
lazypath,
})
end
vim.opt.runtimepath:prepend(lazypath)
Next step is to add lazy.nvim to the top of your init.lua
-- You can use a lua module that contains your plugins.
-- All sub modules of the lua module will also be automatically loaded
-- This is the preferred setup so your plugin specs can be properly cached.
require("lazy").setup("config.plugins", {
-- add any optional configuration here
})
-- Alternatively you can specify a plugin list
require("lazy").setup({
"folke/neodev.nvim",
"folke/which-key.nvim",
{ "folke/neoconf.nvim", cmd = "Neoconf" },
}, {
-- add any optional configuration here
})
🔌 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 |
name | string? |
A custom name for the plugin used for the local plugin directory and as the dispay name |
dev | boolean? |
When true , a local plugin directory will be used instead. See config.dev |
lazy | boolean? |
When true , the plugin will only be loaded when needed. Lazy-loaded plugins are automatically loaded when their lua modules are required , or when one of the laz-loading handlers triggers |
enabled | boolean? or fun():boolean |
When false , or if the function returns false, then this plugin will not be used |
dependencies | LazySpec[] |
A list of plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise |
init | fun(LazyPlugin) |
init functions are always executed during startup |
config | fun(LazyPlugin) |
config is executed when the plugin loads |
build | fun(LazyPlugin) |
build is executed when a plugin is installed or updated |
branch | string? |
Branch of the repository |
tag | string? |
Tag of the repository |
commit | string? |
Commit of the repository |
version | string? |
Version to use from the repository. Full Semver ranges are supported |
pin | boolean? |
When true , this plugin will not be included in updates |
event | string? or string[] |
Lazy-load on event |
cmd | string? or string[] |
Lazy-load on command |
ft | string? or string[] |
Lazy-load on filetype |
keys | string? or string[] |
Lazy-load on key mapping |
return {
-- the colorscheme should be available when starting Neovim
"folke/tokyonight.nvim",
-- 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
{ "folke/which-key.nvim", lazy = true },
{
"nvim-neorg/neorg",
-- lazy-load on filetype
ft = "norg",
-- custom config that will be executed when loading the plugin
config = function()
require("neorg").setup()
end,
},
{
"dstein64/vim-startuptime",
-- lazy-load on a command
cmd = "StartupTime",
},
{
"hrsh7th/nvim-cmp",
-- load cmp on InsertEnter
event = "InsertEnter",
-- these dependencies will only be loaded when cmp loads
-- dependencies are always lazy-loaded unless specified otherwise
dependencies = {
"hrsh7th/cmp-nvim-lsp",
"hrsh7th/cmp-buffer",
},
config = function()
-- ...
end,
},
-- you can use the VeryLazy event for things that can
-- load later and are not important for the initial UI
{ "stevearc/dressing.nvim", event = "VeryLazy" },
{
"cshuaimin/ssr.nvim",
-- init is always executed during startup, but doesn't load the plugin yet.
-- init implies lazy loading
init = function()
vim.keymap.set({ "n", "x" }, "<leader>cR", function()
-- this require will automatically load the plugin
require("ssr").open()
end, { desc = "Structural Replace" })
end,
},
{
"monaqa/dial.nvim",
-- lazy-load on keys
keys = { "<C-a>", "<C-x>" },
},
-- local plugins need to be explicitely configured with dir
{ dir = "~/projects/secret.nvim" },
-- you can use a custom url to fetch a plugin
{ url = "git@github.com:folke/noice.nvim.git" },
-- local plugins can also be configure with the dev option.
-- This will use ~/projects/noice.nvim/ instead of fetching it from Github
-- With the dev option, you can easily switch between the local and installed version of a plugin
{ "folke/noice.nvim", dev = true },
}
⚙️ Configuration
lazy.nvim comes with the following defaults:
{
root = vim.fn.stdpath("data") .. "/lazy", -- directory where plugins will be installed
defaults = {
lazy = false, -- should plugins be lazy-loaded?
version = nil,
-- version = "*", -- enable this to try installing the latest stable versions of plugins
},
lockfile = vim.fn.stdpath("config") .. "/lazy-lock.json", -- lockfile generated after running update.
concurrency = nil, ---@type number limit the maximum amount of concurrent tasks
git = {
-- defaults for the `Lazy log` command
-- log = { "-10" }, -- show the last 10 commits
log = { "--since=1 days ago" }, -- show commits from the last 3 days
timeout = 120, -- kill processes that take more than 2 minutes
url_format = "https://github.com/%s.git",
},
dev = {
-- directory where you store your local plugin projects
path = vim.fn.expand("~/projects"),
---@type string[] plugins that match these patterns will use your local versions instead of being fetched from GitHub
patterns = {}, -- For example {"folke"}
},
install = {
-- install missing plugins on startup. This doesn't increase startup time.
missing = true,
-- try to load one of these colorschemes when starting an installation during startup
colorscheme = { "habamax" },
},
ui = {
-- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
border = "none",
icons = {
cmd = " ",
config = "",
event = "",
ft = " ",
init = " ",
keys = " ",
plugin = " ",
runtime = " ",
source = " ",
start = "",
task = "✔ ",
},
throttle = 20, -- how frequently should the ui process render events
},
checker = {
-- automcatilly check for plugin updates
enabled = false,
concurrency = nil, ---@type number? set to 1 to check for updates very slowly
notify = true, -- get a notification when new updates are found
frequency = 3600, -- check for updates every hour
},
performance = {
cache = {
enabled = true,
path = vim.fn.stdpath("state") .. "/lazy.state",
-- Once one of the following events triggers, caching will be disabled.
-- To cache all modules, set this to `{}`, but that is not recommended.
-- The default is to disable on:
-- * VimEnter: not useful to cache anything else beyond startup
-- * BufReadPre: this will be triggered early when opening a file from the command line directly
disable_events = { "VimEnter", "BufReadPre" },
},
reset_packpath = true, -- reset the package path to improve startup time
rtp = {
reset = true, -- reset the runtime path to $VIMRUNTIME and your config directory
---@type string[] list any plugins you want to disable here
disabled_plugins = {
-- "gzip",
-- "matchit",
-- "matchparen",
-- "netrwPlugin",
-- "tarPlugin",
-- "tohtml",
-- "tutor",
-- "zipPlugin",
},
},
},
-- lazy can generate helptags from the headings in markdown readme files,
-- so :help works even for plugins that don't have vim docs.
-- when the readme opens with :help it will be correctly displayed as markdown
readme = {
root = vim.fn.stdpath("state") .. "/lazy/readme",
files = { "README.md" },
-- only generate markdown helptags for plugins that dont have docs
skip_if_doc_exists = true,
},
}
🚀 Usage
📊 Profiler
The profiling view shows you why and how long it took to load your plugins.
🪲 Debug
See an overview of active lazy-loading handlers and what's in the module cache
▶️ Startup Sequence
lazy.nvim does NOT use Neovim packages and even disables plugin loading
completely (vim.go.loadplugins = false
). It takes over the complete
startup sequence for more flexibility and better performance.
In practice this means that step 10 of Neovim Initialization is done by Lazy.
📦 Differences with Packer
-
Plugin Spec:
setup
=>init
requires
=>dependencies
as
=>name
opt
=>lazy
run
=>build
lock
=>pin
module
is auto-loaded. No need to specify