How I Got Started with NeoVim’s Lua Configuration

Four months ago I was still using SpaceVim when I stumbled upon a blog post on how to configure NeoVim with Lua. I then started to create my own configuration. In this post I’ll share the learnings acquired in the process. I hope you will find this useful to create your own configuration!

Why create your own Vim config from scratch?

Vim has been my daily driver for about ten years. Almost from the beginning, I used Vim distributions for ease of configuration. Spf13 vim first and then SpaceVim. With a distribution, one gets a lot of bells and whistle without spending too much time configuring things. So why spend hours setting up NeoVim from scratch?

SpaceVim does provide a lot of options and plugins so that everyone can find the functionalities they need and discover some new useful tricks. This ends up creating long key mappings like <space>ff and leads to long startup time. For instance on my machine with an SSD drive, it needs between 1 and 2 seconds to start. This is a common problem with distributions.

The long startup time issue can be mitigated by starting Vim less often or by choosing a lighter Vim distribution. One could even reuse only the core and some parts of a distribution, leaving out the rest. Regarding the long key mappings issue, shorter ones could be redefined. However, this has two major drawbacks:

• your customized configuration lies on the moving foundations of the underlying distributions,
• debugging is made more difficult because of the incorporation of so much code you haven’t written and don’t know well.

To solve all these problems, I found it easier and less time-consuming to have my own configuration. Additional benefits include a better recall of what exists and what functionalities are implemented¹. The good news with NeoVim 0.5 is that you can now use Lua and not an arcane language like VimScript². The result is also quite fast: with my configuration NeoVim starts in 100 to 110 milliseconds.

Starting your own configuration does not mean you can’t draw inspiration from other configurations! The next sections of this post reference guides, snippets and plugins I’ve found useful, so that you can evaluate them for inclusion into your own file.

Enjoy the Ride!

To tailor my experience to my liking, I tried my changes in a new instance of NeoVim after every addition of a plugin or of a set of mappings. Mappings in particular sometime looks good on the screen, but fingers don’t like it that much 😀.

In addition, NeoVim configuration can be notoriously complicated to debug. To quote the documentation:

To find the cause of a problem in your config, you must “bisect” it.

For this the previous point about regular testing helps, but I would advise for versioning your configuration, for instance with git and chezmoi. With regular commits, you will be able to rely on the git bisect feature when things go wrong.

Guides

Detailed guidance exists online to get started with your configuration. I got started with a mostly one file Lua configuration. This guide contains general explainations on where to put your Lua files, the reasoning behind the changes… If you are not familiar with NeoVim Lua configuration tricks, I strongly recommend reading the above link. See you in a bit 👋.

In addition, these links may prove useful:

• Example init.lua
• A quick guide to set up nvim built in LSP
• NeoVim’s Lua Resources

Snippets from my Configuration

This section assumes basic knowledge of Lua configuration.

Mapping Hints

Which-Key is a brilliant plugin to display a popup with the possible mappings as you press the keys of the shortcut. For instance, I have mapped <space>j to :tabnew, to open a new tab. On the figure above, I’ve just typed <space> (abbreviated SPC) and the keys that could be pressed then are displayed in a popup at the bottom of the screen. What sets which-key.nvim apart is that you don’t have to configuration your mappings using a special function for it to work. It discovers most of your mappings right away and use them to populate the popup.

I’ve tweaked timeoutlen to get the popup more quickly. I’ve also changed labels for some keys to have shorter or more explicit names, like SPC for <space>.

local wk = require("which-key")
wk.setup {
  key_labels = {
    ["<space>"] = "SPC",
    ["<CR>"] = "RET",
    ["<tab>"] = "TAB",
  },
}
vim.opt.timeoutlen = 900

Mapping Choices

My custom mappings are mainly around the <space> key, often with only one key following, like <space>s to write the current file. The <Leader> key is mostly left for plugins, while the <LocalLeader> is sometimes used for some buffer local mappings.

In general, my mappings are heavily adapted to the BÉPO layout, a Dvorak-like keyboard for French.

Clever-F

rhysd/clever-f.vim extends f, t… so that:

1. When you press fc, all characters c in the current line get highlighted
2. Another press on f jumps to the next occurence of c
3. A press on F jumps backward

This makes , and ; redondant and these can be remapped.

Leaders

The universal leader is by default mapped on \. However, it is frequently remapped to ,, which is easier to reach. Since clever-f freed two mappings, I reuse them like so:

g.mapleader = ","
g.maplocalleader = ";"

Buffer Jump

With the awesome hop.nvim, one can get hints to jump to various parts of a buffer (see the figure below if that does not make sense just yet). It is similiar to EasyMotions and supports jumps by line, word, characters sequences and pattern. However, in my opinion this plugin is not replacement for w and the like, because for short movements I find w or f shorter to type and because the need to read the screen for caracters may be quite slow compared to 3w. It is also not a replacement for / because hop.nvim highlights whats visible on the current buffer. Thus it fills the void left for medium range move.

Here is my configuration for this plugin:

map('n', 'T', '<cmd>HopLineStart<CR>')
map('v', 'T', '<cmd>HopLineStart<CR>')
map('n', 'S', '<cmd>HopWord<CR>')
map('v', 'S', '<cmd>HopWord<CR>')
map('n', 'è', '<cmd>HopChar2<CR>')
map('v', 'è', '<cmd>HopChar2<CR>')
map('n', 'È', '<cmd>HopPattern<CR>')
map('v', 'È', '<cmd>HopPattern<CR>')
require('hop').setup {
  keys = 'auietsrncbpovdljyxqghf', -- Hint keys
}

It is heavily optimized for the the BÉPO layout, whose home row contains the auie keys on the left hand and the tsrn keys on the right hand. Hence the choice to put most mappings on T and S, easily reachable with the right hand and to start the hint keys with auie on the left hand.

Plugins

These plugin are often mostly written in Lua, although vim script plugins can be more mature. The Lua-plugin ecosystem is moving really quickly, you may find that other plugins are more suitable in a couple months.

Plugins I use

Telescope

I use telescope.nvim as a fuzzy finder. It can be slow at times compared to skim or fzf. However, it is relatively easy to script in Lua, making it easy to tightly integrate with other functions.

Completion-nvim

I use nvim-lua/completion-nvim in particular for its chains of completion (several completion sources are chained and sources lower in the chain are used when upper sources don’t have any results). However, nvim-compe may be a better choice if you start fresh.

Complete List

This is a list of plugins I use, roughly ordered by frequency of use.

Plugins I load lazily

I lazy load less often used plugins, so that they are not loaded at startup by default.

• romgrk/nvim-treesitter-context is a bit slow and buggy, but useful sometimes to get the context piled up at the top
• mattn/emmet-vim CSS abbreviations to generate HTML and other
• jbyuki/instant.nvim for remote pair programming

Plugins on my Radar for the Future

Plugins I might use in the future to replace existing pieces or add features:

• vimspector a debugger based on the DAP protocol (like LSP, but for debugguers)
• lspsaga.nvim a UI for the native LSP client
• nvim-compe a completion engine with more advanced support for LSP. I quite like the chains in completion-nvim, but maybe nvim-compe could be a better fit at some point
• gina.vim to replace fugitive. It offers faster startup time and asynchronous git operations

Other Interesting Configurations

• tjdevries
• ojroques

Thanks

Thanks to moverest and J. Guereiro for reviewing drafts of this post.