Converting neovim config to lua

Since I’m using neovim 0.5 on all of my computers, and since I really like Lua as a language, I decided to switch my vim config files over to full lua.

While you can find some docs about converting, they don’t tend to cover everything, so I ended up doing a fair bit of guess and test to get this all working. Hopefully these before/after examples help you!

Init file(s)

I had previously set up my ~/.config/nvim/init.lua to just source my existing .vimrc file. For the sake of the conversion, I’ve decided not to worry about vim-compatibility - I’m doing everything the neovim way, and I’m leaving ~/.vimrc as its own file with a very limited no-plugin config if I ever find myself in vim rather than neovim.

Here’s the main file layout I’m using now:

  • ~/.config/nvim/init.lua: main neovim config, requires more specific files
    • ~/.config/nvim/lua/options.lua: set main options
    • ~/.config/nvim/lua/plugins.lua: the list of plugins I’m loading
    • ~/.config/nvim/lua/plugin-config.lua: config specific to plugins
    • ~/.config/nvim/lua/autocommands.lua: my extra autocommands, mainly filetype stuff
    • ~/.config/nvim/lua/keybindings.lua: custom keybindings
    • ~/.config/nvim/colors/chinook.lua: lua colorscheme (one and only)
  • ~/.vimrc: basic vimscript config for vim, totally separate from neovim now!

Loading both Lua and vimscript

This turns out to be quite simple from within init.lua. Use vim.cmd to run the vimscript source command just like you would have before.

-- init.lua

-- source a vimscript file
vim.cmd('source ~/.vim/old_config.vim')

-- require `new_config.lua` from the nvim/lua folder:
require("new_config")

This is nice because you can leave all of your existing config in vimscript and load the bits that you’ve converted from lua. Eventually one everything is converted (assuming you want to go that far!), you won’t need to source any vimscript files.

Including lua in vimscript configs

I was originally running a small amount of lua inline in my vimscript configs using the lua keyword and a heredoc string. Example:

" customize gitsigns
lua <<EOF
require('gitsigns').setup {
  signs = {
    add          = {hl = 'GitSignsAdd'   , text = '┃', numhl='GitSignsAddNr'   , linehl='GitSignsAddLn'},
    change       = {hl = 'GitSignsChange', text = '║', numhl='GitSignsChangeNr', linehl='GitSignsChangeLn'},
    delete       = {hl = 'GitSignsDelete', text = '▁', numhl='GitSignsDeleteNr', linehl='GitSignsDeleteLn'},
    topdelete    = {hl = 'GitSignsDelete', text = '▔', numhl='GitSignsDeleteNr', linehl='GitSignsDeleteLn'},
    changedelete = {hl = 'GitSignsChange', text = '╣', numhl='GitSignsChangeNr', linehl='GitSignsChangeLn'},
  },
}
EOF

Obviously once I moved this to a .lua config files I could run this code directly.

Setting options

Since neovim 0.5, it’s super easy to set options from lua! Just use vim.opt.

Vimscript version

set wrapscan " wrap searches around top/bottom of file
set nowritebackup " no tilde files
set switchbuf=useopen " use an already open window if possible
set splitright " open vsplits in a more natural spot
set textwidth=0 " never wrap lines
set scrolloff=5 " start scrolling when within 5 lines near the top/bottom

Lua version

-- options.lua

vim.opt.wrapscan = true -- wrap searches around top/bottom of file
vim.opt.writebackup = false -- no tilde files
vim.opt.switchbuf = 'useopen' -- use an already open window if possible
vim.opt.splitright = true -- open vsplits in a more natural spot
vim.opt.textwidth = 0 -- never wrap lines
vim.opt.scrolloff = 5 -- start scrolling when within 5 lines near the top/bottom

Coding in your config

Because lua is a normal programming language, you can easily use variables to keep things in sync, or run some extra commands. Here’s a couple of examples:

reusable variables

-- keep indentation consistent
local indent = 2
vim.opt.tabstop = indent
vim.opt.shiftwidth = indent
vim.opt.softtabstop = indent

Colorscheme

I switched to a lua colorscheme, which works fine directly from the colors/ folder since neovim 0.5.

  • ~/.config/nvim/colors/chinook.lua

To use the colorscheme, I have some lines in options.lua file (uses the same opt function as above):

Vimscript version

" colours and fonts
set background dark
colorscheme chinook
syntax enable

Lua version

-- colours and fonts
vim.opt.background = 'dark'
vim.cmd('colorscheme chinook')
vim.cmd('syntax enable')

I’m not sure if there’s a more neovim way to do these, but certain things seem to still need vimscript commands to make them happen. That may change in future neovim versions too.

For a good example of a lua colorscheme, check our zephyr

Assigning variables

Variables mainly came up when I was configuring my vimscript-based plugins from within my lua config files.

Vimscript version

let g:python3_host_prog='/usr/bin/python3'

let g:deoplete#enable_at_startup = 1

let g:ale_linters = {
\   'typescript': ['eslint', 'tslint'],
\   'ruby': ['rubocop'],
\   'jsx': ['stylelint', 'eslint', 'tslint']
\}

let g:ale_fixers = {
\   '*': ['remove_trailing_lines', 'trim_whitespace'],
\}

Lua version

vim.g.python3_host_prog = '/usr/bin/python3'

vim.g['deoplete#enable_at_startup'] = 1

vim.g.ale_linters = {
    typescript = {'eslint', 'tslint'},
    ruby = {'rubocop'},
    jsx = {'stylelint', 'eslint', 'tslint'},
}

vim.g.ale_fixers = {
   ['*'] = {'remove_trailing_lines', 'trim_whitespace'},
}

Keep in mind a couple of lua language things while converting:

  • lua uses {} for arrays/lists as well as for dictionaries
  • foo.bar and foo['bar'] are identical, which lets you use strings with special chars as keys
  • you need to “escape” lua table keys when setting them if they have special chars in them
    • eg my.table = {easy_key = 6, ['hard key'] = 7}

Keybindings

This is a spot where it gets much much more understandable in lua. I’m using a wrapper function to set reasonable defaults.

Vimscript version

let mapleader=',' " change the <leader> key to be comma

map <F1> <Esc> " avoid opening help on F1, let it be escape instead
imap <F1> <Esc>
nnoremap <CR> :noh<CR><CR> " hit enter to clear search highlighting
imap <expr><silent><C-h> pumvisible() ? deoplete#close_popup() .
      \ "\<Plug>(neosnippet_jump_or_expand)" : "\<CR>"

Lua Version

-- keybindings.lua

-- need a map method to handle the different kinds of key maps
local function map(mode, combo, mapping, opts)
  local options = {noremap = true}
  if opts then
    options = vim.tbl_extend('force', options, opts)
  end
  vim.api.nvim_set_keymap(mode, combo, mapping, options)
end

vim.g.mapleader = ',' -- change the <leader> key to be comma

map('', '<F1>', '<Esc>') -- avoid opening help, treat it like escape (all modes)
map('n', '<CR>', ':noh<CR><CR>', {noremap = true}) -- clears search highlight & still be enter
map('i', '<C-h>', 'pumvisible() ? deoplete#close_popup() ' ..
    			  '"<Plug>(neosnippet_jump_or_expand)": "<CR>"', {expr = true, silent = true})

Plugin Managers

I originally had a heck of a time getting lua require to find plugins when I was using pathogen to manage plugins. Switching to vim-plug fixed that, but I ended up switching to paq as a pure-lua plugin manager since it did everything I needed and ended up being faster.

I may have just been doing something silly with pathogen plugins, but since even the author recommends other plugin managers these days it made sense to change.

Avoiding require errors

This is more for when you’re messing with different plugins, but it’s possible to make a lua require not throw errors on startup when that plugin isn’t installed. There’s a few ways to do it listed online, but I wrote a slightly different one:

-- plugin-config.lua

function has_module(name)
  if pcall(function() require(name) end) then
    return true
  else
    return false
  end
end

if has_module('gitsigns') then
  require('gitsigns').setup {}
-- etc

Is if faster?

TL;DR: loading from Lua files isn’t noticeably faster, but since I switched to treesitter and lua plugins, everything sped up.

My methodology was to run 2 profiling tools:

  • https://github.com/hyiltiz/vim-plugins-profile to generate graphs
    • I had to modify it slightly to know about the paq plugin manager. I used the perl version
  • nvim --startuptime vim_profile.fulllua.log to get overall timing numbers

Vimscript Startup time

Full startup time: 320ms

The 4 slowest scripts were:

  • vim plugin loading (pathogen): > 50ms
  • main.vim (where I set most of my options): 18ms
  • neovim filetype.vim (filetype detection): 16ms
  • colorscheme (jwombat, my custom colorscheme): 4ms

Vimscript startup graph

Lua Startup time

Full startup time: 185ms

The 4 slowest scripts were:

  • neovim filetype.vim (filetype detection): 9ms
  • plugin loading (paq): > 5ms
  • paq.nvim (the loader itself): 4ms
  • colorscheme (chinook): 4ms

Update

After some more tweaking, my startup time is down to 80ms! That’s amazing!

Comparison

After the dust settled, I’d cut over 40% off of my startup time! It was already quite fast, and everyone’s setup will be different.

Reasons things sped up:

  • I switched to treesitter which got rid of a ton of plugins
    • also appears to have sped up neovim filetype detection on startup
  • I switched from pathogen to paq
  • I switched to other lua-based plugins
  • setting options seems to actually be faster in lua

The primary reason that it’s faster is almost certainly the switch to lighter-weight lua plugins. But I wouldn’t have been able to use those without switching at least parts of my neovim config to lua first!

Summary

The good

  • Actually easy to run both vimscript and lua side-by-side
  • Cleaner & more powerful config
  • If you know lua aleady, it’s a lot easier and more fun to write
  • I switched up a bunch of plugins which made things faster

The Bad

Neovim 0.5 could still stand to make some of these things easier, and in some cases there are already PRs up to do that.

  • Some things end up being more work, autocommands in particular still aren’t doable without vimscript
  • if you don’t know lua already, there’s a learning curve there
  • lua on its own isn’t really faster, though setting options seems to be!

The Ugly

  • Some things still require vimscript commands
  • might not play nice with your plugin manager (pathogen)

Overall, I’m happy I spent the time to convert everything, and I’ve got a super fast editor no matter what!