Extending Nvim

Using Vim packages packages

A Vim "package" is a directory that contains plugins. Compared to normal plugins, a package can...

Nvim searches for :runtime files in:

Note that the "pack/*/start/*" paths are not explicitly included in 'runtimepath', so they will not be reported by ":set rtp" or "echo &rtp". Scripts can use nvim_list_runtime_paths() to list all used directories, and nvim_get_runtime_file() to query for specific files or sub-folders within the runtime path. Example:

" List all runtime dirs and packages with Lua paths.
:echo nvim_get_runtime_file("lua/", v:true)

Let's assume your Nvim files are in "~/.local/share/nvim/site" and you want to add a package from a zip archive "/tmp/foopack.zip":

% mkdir -p ~/.local/share/nvim/site/pack/foo
% cd ~/.local/share/nvim/site/pack/foo
% unzip /tmp/foopack.zip

The directory name "foo" is arbitrary, you can pick anything you like.

You would now have these files under ~/.local/share/nvim/site:

pack/foo/README.txt
pack/foo/start/foobar/plugin/foo.vim
pack/foo/start/foobar/syntax/some.vim
pack/foo/opt/foodebug/plugin/debugger.vim

On startup after processing your config, Nvim scans all directories in 'packpath' for plugins in "pack/*/start/*", then loads the plugins.

To allow for calling into package functionality while parsing your vimrc, :colorscheme and autoload will both automatically search under 'packpath' as well in addition to 'runtimepath'. See the documentation for each for details.

In the example Nvim will find "pack/foo/start/foobar/plugin/foo.vim" and load it.

If the "foobar" plugin kicks in and sets the 'filetype' to "some", Nvim will find the syntax/some.vim file, because its directory is in the runtime search path.

Nvim will also load ftdetect files, if there are any.

Note that the files under "pack/foo/opt" are not loaded automatically, only the ones under "pack/foo/start". See pack-add below for how the "opt" directory is used.

Loading packages automatically will not happen if loading plugins is disabled, see load-plugins.

To load packages earlier, so that plugin/ files are sourced: :packloadall This also works when loading plugins is disabled. The automatic loading will only happen once.

If the package has an "after" directory, that directory is added to the end of 'runtimepath', so that anything there will be loaded later.

If you don't have a package but a single plugin, you need to create the extra directory level:

% mkdir -p ~/.local/share/nvim/site/pack/foo/start/foobar
% cd ~/.local/share/nvim/site/pack/foo/start/foobar
% unzip /tmp/someplugin.zip

You would now have these files:

pack/foo/start/foobar/plugin/foo.vim
pack/foo/start/foobar/syntax/some.vim

From here it works like above.

To load an optional plugin from a pack use the :packadd command:

:packadd foodebug

This searches for "pack/*/opt/foodebug" in 'packpath' and will find ~/.local/share/nvim/site/pack/foo/opt/foodebug/plugin/debugger.vim and source it.

This could be done if some conditions are met. For example, depending on whether Nvim supports a feature or a dependency is missing.

You can also load an optional plugin at startup, by putting this command in your config:

:packadd! foodebug

The extra "!" is so that the plugin isn't loaded if Nvim was started with --noplugin.

It is perfectly normal for a package to only have files in the "opt" directory. You then need to load each plugin when you want to use it.

Since color schemes, loaded with :colorscheme, are found below "pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend you put them below "pack/*/opt", for example "~/.config/nvim/pack/mycolors/opt/dark/colors/very_dark.vim".

Filetype plugins should go under "pack/*/start", so that they are always found. Unless you have more than one plugin for a file type and want to select which one to load with :packadd. E.g. depending on the compiler version:

if foo_compiler_version > 34
  packadd foo_new
else
  packadd foo_old
endif

The "after" directory is most likely not useful in a package. It's not disallowed though.

Creating Vim packages package-create

This assumes you write one or more plugins that you distribute as a package.

If you have two unrelated plugins you would use two packages, so that Vim users can choose what they include or not. Or you can decide to use one package with optional plugins, and tell the user to add the preferred ones with :packadd.

Decide how you want to distribute the package. You can create an archive or you could use a repository. An archive can be used by more users, but is a bit harder to update to a new version. A repository can usually be kept up-to-date easily, but it requires a program like "git" to be available. You can do both, github can automatically create an archive for a release.

Your directory layout would be like this:

start/foobar/plugin/foo.vim          " always loaded, defines commands
start/foobar/plugin/bar.vim          " always loaded, defines commands
start/foobar/autoload/foo.vim        " loaded when foo command used
start/foobar/doc/foo.txt             " help for foo.vim
start/foobar/doc/tags                " help tags
opt/fooextra/plugin/extra.vim        " optional plugin, defines commands
opt/fooextra/autoload/extra.vim      " loaded when extra command used
opt/fooextra/doc/extra.txt           " help for extra.vim
opt/fooextra/doc/tags                " help tags

This allows for the user to do:

mkdir ~/.local/share/nvim/site/pack
cd ~/.local/share/nvim/site/pack
git clone https://github.com/you/foobar.git myfoobar

Here "myfoobar" is a name that the user can choose, the only condition is that it differs from other packages.

In your documentation you explain what the plugins do, and tell the user how to load the optional plugin:

:packadd! fooextra

You could add this packadd command in one of your plugins, to be executed when the optional plugin is needed.

Run the :helptags command to generate the doc/tags file. Including this generated file in the package means that the user can drop the package in the pack directory and the help command works right away. Don't forget to re-run the command after changing the plugin help:

:helptags path/start/foobar/doc
:helptags path/opt/fooextra/doc

Suppose you have two plugins that depend on the same functionality. You can put the common functionality in an autoload directory, so that it will be found automatically. Your package would have these files:

pack/foo/start/one/plugin/one.vim

call foolib#getit()

pack/foo/start/two/plugin/two.vim

call foolib#getit()

pack/foo/start/lib/autoload/foolib.vim

func foolib#getit()

This works, because start packages will be searched for autoload files, when sourcing the plugins.

Plugin manager vim.pack

Install, update, and delete external plugins. WARNING: It is still considered experimental, yet should be stable enough for daily use.

Manages plugins only in a dedicated vim.pack-directory (see packages): site/pack/core/opt subdirectory of "data" standard-path. Subdirectory site of "data" standard path needs to be part of 'packpath'. It usually is, but might not be in cases like --clean or setting $XDG_DATA_HOME during startup. Plugin's subdirectory name matches plugin's name in specification. It is assumed that all plugins in the directory are managed exclusively by vim.pack.

Uses Git to manage plugins and requires present git executable. Target plugins should be Git repositories with versions as named tags following semver convention v<major>.<minor>.<patch> (with or without v prefix). Like v1.2.0 or 1.2.0, but not 1.2 or v1.

The latest state of all managed plugins is stored inside a vim.pack-lockfile located at 'packlockfile'. It is a JSON file that is used to persistently track data about plugins. For a more robust config treat lockfile like its part: put under version control, etc. In this case all plugins from the lockfile will be installed at once (in alphabetical order) and at lockfile's revision (instead of inferring from version). This is done on the very first vim.pack function call to ensure that lockfile is aligned with what is actually on the disk. Lockfile should not be edited by hand. Corrupted data for installed plugins is repaired (including after deleting whole file), but version fields will be missing for not yet added plugins.

Create custom Lua helpers:

local gh = function(x) return 'https://github.com/' .. x end
local cb = function(x) return 'https://codeberg.org/' .. x end
vim.pack.add({ gh('user/plugin1'), cb('user/plugin2') })

Another approach is to utilize Git's insteadOf configuration:

:packu[pdate][!] [++offline] [++lockfile] [name]

Interactively update the specified plugins. Skips confirmation when ! is given. If no plugin names are provided, update all plugins.

When ++offline is given, skip downloading new updates.

When ++lockfile is given, use revisions from the lockfile.

:packd[el][!] {name}

Remove the specified plugins. Can only remove inactive plugins unless ! is given.

:packd[el][!] ++all

Remove all inactive plugins. When ! is given, instead remove all plugins.

Performing actions via vim.pack functions can trigger these events:

Events are triggered in bulk respecting order of plugins in which they are supplied. First all PackChangedPre, then perform all actions, and only after

The event-data has these keys (type: vim.event.packchanged.data):

These events can be used to execute plugin hooks. For example:

local hooks = function(ev)
  -- Use available |event-data|
  local name, kind = ev.data.spec.name, ev.data.kind

  -- Run build script after plugin's code has changed
  if name == 'plug-1' and (kind == 'install' or kind == 'update') then
    -- Append `:wait()` if you need synchronous execution
    vim.system({ 'make' }, { cwd = ev.data.path })
  end

  -- If action relies on code from the plugin (like user command or
  -- Lua code), make sure to explicitly load it first
  if name == 'plug-2' and kind == 'update' then
    if not ev.data.active then
      vim.cmd.packadd('plug-2')
    end
    vim.cmd('PlugTwoUpdate')
    require('plug2').after_update()
  end
end

-- If hooks need to run on install, run this before `vim.pack.add()`
-- To act on install from lockfile, run before very first `vim.pack.add()`
vim.api.nvim_create_autocmd('PackChanged', { callback = hooks })

Plugins can come with a special top level pkg.json manifest file with extra information. If present, vim.pack uses it for improved user experience:

Full specification see at https://packspec.org/. See also vim.pack.Manifest. A simple example:

{
 "name": "best-plugin.nvim",
 "description": "The best plugin for Neovim",
 "version": "1.0.0",
 "engines": {
     "nvim": ">=0.13.0",
     "vim": ">=9.1.0"
 },
 "scripts": {
   "install": "scripts/install.lua",
   "preupdate": "scripts/preupdate.vim",
   "update": "scripts/update.vim",
   "preuninstall": "scripts/preuninstall.lua"
 },
 "dependencies": [
   {
     "src": "https://github.com/user/plugin1"
   },
   {
     "src": "https://github.com/user/plugin2",
     "version": ">=1.0.0"
   },
   {
     "src": "https://github.com/user/plugin3",
     "version": "'branch'"
   }
 ]
}

Add plugin to current session

Notes:

Remove plugins from disk

Gets vim.pack plugin info, optionally filtered by names.

(table[]) A list of objects with the following fields:

Update plugins

Notes:

The goal of the confirmation buffer is to show update details for the user to read, confirm (execute :write) or deny (execute :quit) the update.

Pending changes starting with > will be applied while the ones starting with < will be reverted.

There are convenience buffer-local mappings:

Some features are provided via LSP: