- Install - · - Configure - · - Docs -
- - - - +# 💤 lazy.nvim **lazy.nvim** is a modern plugin manager for Neovim. - + ## ✨ Features -- 📦 Manage all your Neovim plugins with a powerful UI -- 🚀 Fast startup times thanks to automatic caching and bytecode compilation of Lua modules +- 📦 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 +- 🔌 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 @@ -54,16 +22,315 @@ - 🔎 Automatically check for updates - 📋 Commit, branch, tag, version, and full [Semver](https://devhints.io/semver) support - 📈 Statusline component to see the number of pending updates -- 🎨 Automatically lazy-loads colorschemes + +## 📄 Table of Contents + + + +- [⚡️ Requirements](#-requirements) + - [📦 Installation](#-installation) + - [🔌 Plugin Spec](#-plugin-spec) + - [⚙️ Configuration](#-configuration) + - [🚀 Usage](#-usage) + - [📊 Profiler](#-profiler) + - [🪲 Debug](#-debug) + - [▶️ Startup Sequence](#-startup-sequence) + - [📦 Differences with Packer](#-differences-with-packer) + - [📦 Other Neovim Plugin Managers in Lua](#-other-neovim-plugin-managers-in-lua) + + ## ⚡️ Requirements -- Neovim >= **0.8.0** (needs to be built with **LuaJIT**) -- Git >= **2.19.0** (for partial clones support) -- a [Nerd Font](https://www.nerdfonts.com/) **_(optional)_** -- [luarocks](https://luarocks.org/) to install rockspecs. - You can remove `rockspec` from `opts.pkg.sources` to disable this feature. +- Neovim >= **0.8.0** -## 🚀 Getting Started +## 📦 Installation -Check the [documentation website](https://lazy.folke.io/) for more information. \ No newline at end of file +You can use the following Lua code to bootstrap **lazy.nvim** + + + +```lua +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` + +```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](https://devhints.io/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 | + + + +```lua +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" }, "
- 
- 
- 
- 
- 
- 
-
+
+
-✨ FEATURES *lazy.nvim-🚀-getting-started-✨-features*
-
-- 📦 Manage all your Neovim plugins with a powerful 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
+image
+
+
+
- LazyComment Comment
+🪲 DEBUG *lazy.nvim-🪲-debug*
- LazyCommit @variable.builtin commit ref
+See an overview of active lazy-loading handlers and what’s in the module
+cache
- LazyCommitIssue Number
+
+image
+
+
+
- LazyCommitScope Italic conventional commit
- scope
-
- LazyCommitType Title conventional commit
- type
-
- LazyDimmed Conceal property
-
- LazyDir @markup.link directory
-
- LazyError DiagnosticError task errors
-
- LazyH1 IncSearch home button
-
- LazyH2 Bold titles
-
- LazyInfo DiagnosticInfo task errors
-
- LazyItalic { italic = true }
-
- LazyLocal Constant
-
- LazyNoCond DiagnosticWarn unloaded icon for a
- plugin where cond() was
- false
-
- LazyNormal NormalFloat
-
- LazyProgressDone Constant progress bar done
-
- LazyProgressTodo LineNr progress bar todo
-
- LazyProp Conceal property
-
- LazyReasonCmd Operator
-
- LazyReasonEvent Constant
-
- LazyReasonFt Character
-
- LazyReasonImport Identifier
-
- LazyReasonKeys Statement
-
- LazyReasonPlugin Special
-
- LazyReasonRequire @variable.parameter
-
- LazyReasonRuntime @macro
-
- LazyReasonSource Character
-
- LazyReasonStart @variable.member
-
- LazySpecial @punctuation.special
-
- LazyTaskOutput MsgArea task output
-
- LazyUrl @markup.link url
-
- LazyValue @string value of a property
-
- LazyWarning DiagnosticWarn task errors
- -----------------------------------------------------------------------
-
-==============================================================================
-7. 🚀 Usage *lazy.nvim-🚀-usage*
-
-
-▶️ STARTUP SEQUENCE *lazy.nvim-🚀-usage-▶️-startup-sequence*
+STARTUP SEQUENCE *lazy.nvim-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:
+In practice this means that step 10 of |Neovim Initialization| is done by Lazy.
-1. All the plugins’ `init()` functions are executed
-2. All plugins with `lazy=false` are loaded. This includes sourcing `/plugin` and `/ftdetect` files. (`/after` will not be sourced yet)
-3. All files from `/plugin` and `/ftdetect` directories in your rtp are sourced (excluding `/after`)
-4. All `/after/plugin` files are sourced (this includes `/after` from plugins)
+DIFFERENCES WITH PACKER *lazy.nvim-differences-with-packer*
-Files from runtime directories are always sourced in alphabetical order.
+- **Plugin Spec**:
+ - `setup` => `init`
+ - `requires` => `dependencies`
+ - `as` => `name`
+ - `opt` => `lazy`
+ - `run` => `build`
+ - `lock` => `pin`
+ - `module` is auto-loaded. No need to specify
-🚀 COMMANDS *lazy.nvim-🚀-usage-🚀-commands*
-Plugins are managed with the `:Lazy` command. Open the help with `` to see
-all the key mappings.
+OTHER NEOVIM PLUGIN MANAGERS IN LUA*lazy.nvim-other-neovim-plugin-managers-in-lua*
-You can press `
+image
+