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:
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
You can create an
init.lua file at the root of your configuration directory:
│ └── elem
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.
You should now have the follwing tree:
│ ├── elem
│ └── utils.lua
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")
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
The LuaJit will look in all your rtp paths and
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: