Updating a large old Vim config to Lua
A checklist with every step needed to convert a Vimscript config file to Lua
One of the things I hear from readers regularly is, “I have this complicated years-old Vim config, but I want to start using Neovim. What should I do with it?”
You can get started by just using your existing Vimscript config in Neovim, but “better configuration” is probably one of the reasons you’re moving to Neovim in the first place.
So I’ve written up a really quick checklist that should walk you through the whole process.
Create an
init.lua
and load the old config as a dependency. Check the whole thing in to source control.Convert all the
set
configuration to use thevim.o
APIMove all the configuration-free plugins into the Lua config. You will probably need to switch plugin managers — the best ones in Vimscript don’t have great Lua APIs. I like lazy.nvim
Move each plugin that needs configuration into the Lua plugin manager.
Move any custom keybindings. You may at this point want to start using the which-key plugin, which helps to document keybindings.
Move any custom autocmd bindings.
Move any remaining configuration to use Lua APIs.
If you actually end up with a step 8, I’d really appreciate it if you could send me an e-mail or leave a comment here with what these instructions were missing. Likewise if you try this and get stuck anywhere.
At the end of this process you should be using 100% Lua API, and you should be able to easily add Neovim-only plugins.
You should also be able to start using a language server.
I went on a similar journey. Once I moved to lazy.nvim as the package manager, I noticed my config slowly converged towards Folke's LazyVim distro, so I intentionally completed that convergence. I think it's a great distro. I have since re-configured some of his choices (nvim-cmp, lualine, the winbar, and some telescope mappings) but, overall, I still benefit from one of the best Neovim plugin authors I know staying up to date with the Neovim ecosystem for me. Curious if that's where you'll head, too!