Over the past two years, I have been using vim-plug as my Nvim plugin manager. Vim-plug is powerful, fast and amazing, especially considering that all its features are contained in a single vim script. It uses the old way to manage plugins, i.e., it will manage the loading of plugins directly.

Packages in Vim

In Vim/Nvim, we also have another way to manage plugins, that is, by using packages. It is a new way of organizing plugins. We can split plugins into two types, opt plugins and start plugins. If we put plugins in opt directory under a package, the plugins will not be loaded during initialization. If we want to use plugin foo later, we use :packadd foo to load it. For plugins under start directory, they will be loaded1 by Vim automatically after initialization.

For opt plugin foo, Vim will look for pack/xxx/opt/foo under paths in the option packpath. For start plugins, Vim will look for them under pack/xxx/start/ directory under paths in packpath.

Now enter packer.nvim!

Actually, there are several plugin managers that use the package feature to manage plugins, for example, minpac and vim-packager, which are written in pure vim script.

With the release of the long overdue Nvim 0.5.0 and increasing importance of Lua in configuring and developing Nvim. I would like to try a plugin manager written in Lua, which also supports packages. After some survey, I decide to give packer.nvim a try, which is by far the most powerful and feature-rich plugin manager written in Lua2.

I use the following script to install packer.nvim in my computer:

local execute = vim.api.nvim_command
local fn = vim.fn

local packer_install_dir = fn.stdpath('data')..'/site/pack/packer/start/packer.nvim'

local plug_url_format = ''
if vim.g.is_linux > 0 then
  plug_url_format = 'https://hub.fastgit.org/%s'
else
  plug_url_format = 'https://github.com/%s'
end

local packer_repo = string.format(plug_url_format, 'wbthomason/packer.nvim')
local install_cmd = string.format('10split |term git clone --depth=1 %s %s', packer_repo, packer_install_dir)

if fn.empty(fn.glob(packer_install_dir)) > 0 then
  vim.api.nvim_echo({{'Installing packer.nvim', 'Type'}}, true, {})
  execute(install_cmd)
  execute 'packadd packer.nvim'
end

vim.cmd [[packadd packer.nvim]]

-- the plugin install follows from here
-- ....

I put it under ~/.config/nvim/lua/plugins.lua and in my init.vim, I just require it: lua require('plugins.lua'). With the above script, packer will be automatically installed if it hasn’t.

Some issues I met during transition

Issues for lazy-loaded plugins

Packer’s lazy loading of plugins based on some conditions is really cool, but is also error-prone for newbies. All lazy-loaded plugins are put under opt directory, and they are only added to runtimepath by packer when the specified conditions are met. This is the root cause of many issues related to missing function or modules, etc.

For example, if we use nvim-compe and lazy-load it, but we require its config during Nvim initialization, we will see errors during nvim startup:

module ‘compe’ not found.

One way to fix this is to use config key after the plugin has been loaded. See for example here.

use { 'hrsh7th/nvim-compe', event = 'InsertEnter *', config = [[require('config.compe')]] }

Forget to run PackerCompile after changing plugin setings

After changing plugin configuration, we must run :PackerCompile. It will produce a file named packer_compiled.vim or packer_compile.lua under the directory ~/.config/nvim/plugin.

When something went wrong, always check if you have run :PackerCompile and restarted nvim. 90% time, the issue is gone.

No way to retry plugins that failed during installation

Unlike vim-plug, when plugin installation fails, there is no re-try mechanism. We have to manually run :PackerInstall to re-install the failed plugins.

Plugin loading order

When we want to load plugin A after plugin B and they are both lazy-loaded, there is no need to use event for the plugin A, the after condition is enough:

use {'foo/bar', event = 'VimEnter'}
use {'foo/baz', after = 'bar'}

If we use event for both foo/bar and foo/baz, foo/baz may not be loaded after foo/bar due to the firing of autocmd event. See also this issue.

Issues related to lazy-loaded remote plugins

For nvim remote plugins, we need to run command :UpdateRemotePlugins to make them work properly. By running this command, a minifest file called rplugin.vim will be generated under ~/.local/share/nvim/, which records what kinds of commands a plugin provides (also see :h remote-plugin).

For example, for remote plugin semshi, my initial setup is:

use {'numirias/semshi', run = ':UpdateRemotePlugins', ft = 'python'}

It does not work well. When we run :PackerUpdate (it will run : UpdateRemotePlugins every time we update plugins), semshi may not be in runtimepath. So semshi-related command will be missing in rplugin.vim. Afterwards, when we open a Python file, we see errors that command Semshi enable is not available.

The correct way is to run :UpdateRemotePlugins after semshi is loaded:

use {'numirias/semshi', ft = 'python', config = 'vim.cmd [[UpdateRemotePlugins]]'}

This way, we insure that semshi will be work properly.

Specify the plugin url format

By default, when we use use 'aaa/bbb', packer will try to clone https://github.com/aaa/bbb.git. However, due to speed issue accessing github in certain areas, the user may want to use a mirror site of GitHub, for example, fastgit. Fortunately, this feature has been added recently, under the request of me 😃.

Now, you can do the following:

require('packer').startup(
{
  function(use)
    use 'aaa/bbb'
    use 'foo/bar'
  end,
  config = {
    max_jobs = 16,
    git = {
      default_url_format = 'https://hub.fastgit.org/%s'
    }
  }
})

All your plugins will be clone from fastgit instead of GitHub.

Conclusion

Although there are small issues when switching from vim-plug to packer, it is mainly because I am new to its lazy-loading feature. Overall, packer.nvim is a great choice if you want to manage plugins in lua. Considering that packer is a young plugin and the active development happening in its GitHub repo, I am sure that is will be maturer in short time.

My packer.nvim config can be found here.

References

1. Here, loaded means the plugin directory will be added the runtimepath. ↩︎

2. If you want to minimal plugin manager in lua, try paq. ↩︎

Author jdhao

LastMod 2021-07-12

License CC BY-NC-ND 4.0