Before we start it's important to know lua can only be used in Neovim 0.5 and above. You can check the version of Neovim you have by nvim --version, if you see a version of 0.5 or above, you're good to go.
Some History
Vim is traditionally configured with Vimscript.
Vimscript is infamous for being a not-so-friendly language.
Lua on the other hand is much faster and easier to get a grasp on.
Trade offs, Pros, and more
While Lua is a much easier language to learn than vimscript, configuring Neovim can get especially tedious and verbose as Neovim doesn't provide much out of the box as compared to VSCode and other IDEs.
If you want to quickly get going without spending much time configuring Neovim then I'd recommend using LunarVim. There are plenty of other Preconfigured Configurations too.
That being said, I'd still recommend learning some lua and building your own configuration, the great thing about Neovim is high flexiblity, you can tweak a lot of settings which you never knew you needed.
Lua
To get started with Lua I would recommend taking a look at Learn Lua in Y minutes.
Configuring Neovim
Now like every other configuration when Neovim starts it looks for a configuration file. If you're using a Unix based operating system, like MacOS or Linux it most likely tries to find the file at ~/.config/nvim/ and ~/AppData/Local/nvim/ if you're on Windows. If the nvim folder is not there then you can create it.
If you're unsure where your configuration directory is open neovim and type
:lua print(vim.fn.stdpath('config'))
press enter, and at the bottom of your screen you can see the path of your Neovim Configuration Directory.
Create a file called init.lua in this nvim/ directory.
touch init.lua
init.lua is the file Neovim will look for in the config directory whenever it is opened, and whatever lua code is in the init.lua file will run.
Inside the init.lua file — write the following code
print('Hello from init.lua')
Save the file and restart Neovim and you should see 'Hello from init.lua' printed below.
Modules
Neovim configuration can get large, we would like to have it in multiple files rather than a single large init.lua.
Modules in lua are a bit tricky at first.
Create a folder in your configuration directory (nvim/) called lua/.
mkdir lua
Depending on your Operating System
~/.config/nvim/lua/ OR~/AppData/Local/nvim/lua/
is where all your lua files go.
If you try to import a lua module from any other folder it won't work.
There are a specific set of folder from where you can import a lua module or a vim file, a lua directory is one of them. There folders are called runtime paths. To learn more type :help 'runtimepaths' in Neovim.
Let's create a file called options.lua inside the lua/ folder.
Open the options.lua file and add the following lines:
vim.wo.number = true
Now we want to require or import the options lua module in the main init.lua file.
It can be a bit infuriating to close neovim just to switch to another file assuming you're configuring in Neovim.
Here's a neat trick, type :e ../ and press the tab key, you can use the tab key to go up and down this list and press enter when you have selected init.lua.
You can use this trick to also navigate back to options.lua.
Later we will learn how to install plugins in Neovim to have a directory file tree pane just like other IDEs.
In the init.lua file, remove the existing print statement and type.
require('options')
You don't have to specify lua/ or options.lua and if you do then you will get some error.
Because that's how modules in lua work.
Now before you restart neovim, you don't need to restart it, you can simply use :luafile % and press enter.
This command will execute the code in the current file which is init.lua.
Now, you should get line numbers in Neovim on the right side.
There are a lotttt of options like line numbers that you can have in vim.
While you can do :help options in vim to get a list of options, there are nearly 340 options that vim has.
You can find a list of all options with a small description by typing :help Q_op or by going to this link here
Now going through all of them is quite time consuming so I would recommend copying options someone else has set. You can find a list of options that I use here.
If you don't know what a particular option does, you can always use :help <option name>, again using <tab> complete helps a lot, just start typing the option name and press tab to autocomplete. So if you want to search for what does vim.o.hlsearch does you can simply do :help 'hlsearch'.
End Note
Hopefully this post helps you get started with some understanding of how to use Lua modules and how to configure Neovim in lua in general. In the next post we will be looking at a neat way to configure keybinds or keymaps in Neovim.
The post to configure keymaps in Neovim is out.
There are a lot of things that I want to cover in this series —
- Neovim Plugins
- Language Server Protocol (LSP)
- Setting up tools like Prettier and ESLint
- Snippets
- Other Neovim optimizations and Hacks
Give me a follow on Twitter @yashguptaz so you don't miss out on any of the future posts. Do let me know if my post helped me on Twitter (DMs open).