Skip to main content

🔌 Plugin Spec

Spec Source

PropertyTypeDescription
[1]string?Short plugin url. Will be expanded using config.git.url_format. Can also be a url or dir.
dirstring?A directory pointing to a local plugin
urlstring?A custom git url where the plugin is hosted
namestring?A custom name for the plugin used for the local plugin directory and as the display name
devboolean?When true, a local plugin directory will be used instead. See config.dev

A valid spec should define one of [1], dir or url.

Spec Loading

PropertyTypeDescription
dependenciesLazySpec[]A list of plugin names or plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise. When specifying a name, make sure the plugin spec has been defined somewhere else.
enabledboolean? or fun():booleanWhen false, or if the function returns false, then this plugin will not be included in the spec
condboolean? or fun(LazyPlugin):booleanBehaves the same as enabled, but won't uninstall the plugin when the condition is false. Useful to disable some plugins in vscode, or firenvim for example.
prioritynumber?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.

Spec Setup

PropertyTypeDescription
initfun(LazyPlugin)init functions are always executed during startup. Mostly useful for setting vim.g.* configuration used by Vim plugins startup
optstable or fun(LazyPlugin, opts:table)opts should be a table (will be merged with parent specs), return a table (replaces parent specs) or should change a table. The table will be passed to the Plugin.config() function. Setting this value will imply Plugin.config()
configfun(LazyPlugin, opts:table) or trueconfig is executed when the plugin loads. The default implementation will automatically run require(MAIN).setup(opts) if opts or config = true is set. Lazy uses several heuristics to determine the plugin's MAIN module automatically based on the plugin's name. (opts is the recommended way to configure plugins).
mainstring?You can specify the main module to use for config() and opts(), in case it can not be determined automatically. See config()
buildfun(LazyPlugin) or string or false or a list of build commandsbuild is executed when a plugin is installed or updated. See Building for more information.

Always use opts instead of config when possible. config is almost never needed.

GOOD
{ "folke/todo-comments.nvim", opts = {} },
BAD
{
"folke/todo-comments.nvim",
config = function()
require("todo-comments").setup({})
end,
},

Spec Lazy Loading

PropertyTypeDescription
lazyboolean?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 lazy-loading handlers triggers
eventstring? or string[] or fun(self:LazyPlugin, event:string[]):string[] or {event:string[]|string, pattern?:string[]|string}Lazy-load on event. Events can be specified as BufEnter or with a pattern like BufEnter *.lua
cmdstring? or string[] or fun(self:LazyPlugin, cmd:string[]):string[]Lazy-load on command
ftstring? or string[] or fun(self:LazyPlugin, ft:string[]):string[]Lazy-load on filetype
keysstring? or string[] or LazyKeysSpec[] or fun(self:LazyPlugin, keys:string[]):(string | LazyKeysSpec)[]Lazy-load on key mapping

Refer to the Lazy Loading section for more information.

Spec Versioning

PropertyTypeDescription
branchstring?Branch of the repository
tagstring?Tag of the repository
commitstring?Commit of the repository
versionstring? or false to override the defaultVersion to use from the repository. Full Semver ranges are supported
pinboolean?When true, this plugin will not be included in updates
submodulesboolean?When false, git submodules will not be fetched. Defaults to true

Refer to the Versioning section for more information.

Spec Advanced

PropertyTypeDescription
optionalboolean?When a spec is tagged optional, it will only be included in the final spec, when the same plugin has been specified at least once somewhere else without optional. This is mainly useful for Neovim distros, to allow setting options on plugins that may/may not be part of the user's plugins.
specsLazySpecA list of plugin specs defined in the scope of the plugin. This is mainly useful for Neovim distros, to allow setting options on plugins that may/may not be part of the user's plugins. When the plugin is disabled, none of the scoped specs will be included in the final spec. Similar to dependencies without the automatic loading of the specs.
modulefalse?Do not automatically load this Lua module when it's required somewhere
importstring?Import the given spec module.