How to have a Neovim configuration compatible with Vim

So you can have your cake and eat it too.

I have been a Vim user for about 8 years already. Most of this time I have written code using Neovim, and when they announced the Lua integration, I was excited about the possibilities. I use my Vim configuration at home but also at work. In Booking.com, we do a reasonable amount of development in remote machines. Typically, you use ssh to remotely access a machine and do your work there. Many of those machines are quite liberal in regards of installing external packages (which includes Neovim), but other are heavily locked. However, we have an internal system that allows you to copy your dot files when you connect to a remote machine.

For most of these years, I have kept my configuration compatible between Vim and Neovim. Every Vim configuration should work on Neovim by default, but the other way around. I managed to keep the especial Neovim features and plug-ins under wards so if needed I could launch the configuration in Vim if Neovim wasn’t available in the environment. This solution will not work anymore when with Lua plug-ins are involved.

The requirements

These are the MUST have for the configuration.

• It must work in Neovim and Vim with similar functionalities so it does not break my muscle memory.
• It must be a single configuration that works out of the box. If not, there will be two different configurations de facto.
• Neovim can use Lua and external software (for example, language servers or tools like eslint) without limitations. It will be running in my local machine or in a non critical server.
• Vim can only use Vimscript. It can use plug-ins as far as they are written exclusively in Vimscript and can be tracked on git. This will run on restricted servers that only allow to copy configuration files.
• Minimise dependencies but keep it fast (Lua plug-ins > Vim plug-ins > external tools).

The solution

How my Neovim configuration directory looks like.

This is how my (Neo)vim configuration looks like. The directory lives in $HOME/.config/nvim, which is the default location for Neovim. When I need to use Vim, I set two symbolic links: $HOME/.config/nvim→ $HOME/.vim…