A quick guide to configure Neovim in lua

A small disclaimer first: this guide supposes that you have the HEAD version of Neovim and that you know at least a little bit about Lua. If you don’t you can read this quick guide for Lua in Neovim.

Why use lua for your Neovim configuration?

Lua is very weel integrated with Neovim, and with LuaJIT, it is much faster than vimscript. If you are like me and never were a big fan of VimScript, then this guide will help you to get rid of most of your VimScript configurations.

Your configuration directory tree

First we will create a few directories in the .config/nvim directory. Let’s create the plugin directory, for configurations of plugins we can’t write in lua (this directory will be empty in this tutorial, it will be for your own use later), then the lua directory for all of your lua plugins configuration. You should have the following tree:

~/.config/nvim
├── lua
└── plugin

In your lua directory, you can create a directory with your username, so you can source the files in it that have the same name as the plugin files. Mine is named elem

~/.config/nvim
├── lua
│   └── elem
└── plugin

Writing your init.lua file

You can create an init.lua file at the root of your configuration directory:

~/.config/nvim
├── init.lua
├── lua
│   └── elem
└── plugin

This file will be automatically sourced by Neovim and we will put all of our configurations here. You can have your old init.vim file open on the side to copy your different options.

One thing to know about vim options is that they can be either global, window local or buffer local. This is not show in VimScript because we always set them with this syntax set <option> = <value> . However in Lua, the scope of the option matters as we have to set them by scope.

Let’s put the few first lines of our config file to handle that.

local o = vim.o -- For the globals options
local w = vim.wo -- For the window local options
local b = vim.bo -- For the buffer local options

There are a few functions we will have to use quite a lot in our configuration file, to avoid writing them again and again, let’s create a lua/utils.lua file to contain them.

The `lua/utils.lua` file

You should now have the follwing tree:

~/.config/nvim
├── init.lua
├── lua
│   ├── elem
│   └── utils.lua
└── plugin

We can now start to add our options to the init.lua file. Take the first few options of your old configuration file and look up the help portion for this function, it will tell you the cope of the option, for example for the backspace option you can do :h 'backspace' and you’ll see the following text:

'backspace' 'bs' string (default "indent,eol,start")
   global
 Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert
 mode.  This is a list of items, separated by commas.  Each item allows
 a way to backspace over something:
 value effect ~
 indent allow backspacing over autoindent
 eol allow backspacing over line breaks (join lines)
 start allow backspacing over the start of insert; CTRL-W and CTRL-U
  stop once at the start of insert.
 nostop like start, except CTRL-W and CTRL-U do not stop at the start of
  insert.
When the value is empty, Vi compatible backspacing is used.
For backwards compatibility with version 5.4 and earlier:
 value effect ~
   0 same as ":set backspace=" (Vi compatible)
   1 same as ":set backspace=indent,eol"
   2 same as ":set backspace=indent,eol,start"
   3 same as ":set backspace=indent,eol,nostop"

You can see on the second line global , this means to set the option, you’ll have to do o.backspace = <your preferred value> . If the option is window local you’ have the line: local to window , and for buffer local: local to buffer . You can now check the options and set them to the value you wish, you can check the type of the option in the same help section, for backspace it is a string , the type is given on the first line.

You should now set all your options. For the filetype option, you have to call the cmd function, as well as for the syntax on option, as an example, my options are set as so:

You can now use lua for all of your configurations. In your username folder, you should setup your plugins in lua, and require them in your init.lua file, for example if you have a lua/elem/telescope.lua file for your telescope configuration, you can add this line in your init.lua file:

require('elem.telescope')

The LuaJit will look in all your rtp paths and <rtp>/lua paths.

If you want to check what a full configuration looks like and take some inspirations, you can check my dotfiles repository.

For your plugins, if you want to have them in lua, you should checkout packer.nvim.

I hope you found this guide useful and if you have any questions do not hesitate to comment.

You can also check my other Neovim guides:

• A quick guide to set up nvim built in LSP