Getting started using Lua in Neovim

Introduction

The integration of Lua as a first-class language inside Neovim is shaping up to be one of its killer features. However, the amount of teaching material for learning how to write plugins in Lua is not as large as what you would find for writing them in Vimscript. This is an attempt at providing some basic information to get people started.

This guide assumes you are using the latest nightly build of Neovim.

Learning Lua

If you are not already familiar with the language, there are plenty of resources to get started:

• The Learn X in Y minutes page about Lua should give you a quick overview of the basics
• If videos are more to your liking, Derek Banas has a 1-hour tutorial on the language
• The lua-users wiki is full of useful information on all kinds of Lua-related topics
• The official reference manual for Lua should give you the most comprehensive tour of the language

It should also be noted that Lua is a very clean and simple language. It is easy to learn, especially if you have experience with similar scripting languages like JavaScript. You may already know more Lua than you realise!

Note: the version of Lua that Neovim embeds is Lua 5.1, or more specifically LuaJIT

Existing tutorials for writing Lua in Neovim

A few tutorials have already been written to help people write plugins in Lua. Some of them helped quite a bit when writing this guide. Many thanks to their authors.

• teukka.tech - From init.vim to init.lua
• 2n.pl - How to write neovim plugins in Lua

Where to put Lua files

Lua files are typically found inside a lua/ folder in your runtimepath (for most users, this will mean ~/.config/nvim/lua on *nix systems and ~/AppData/Local/nvim/lua on Windows). The package.path and package.cpath globals are automatically adjusted to include lua files in this folder. This means you can require() these files as Lua modules.

Let's take the following folder structure as an example:

📂 ~/.config/nvim
├── 📁 after
├── 📁 ftplugin
├── 📂 lua
│  ├── 🌑 myluamodule.lua
│  └── 📂 other_modules
│     ├── 🌑 anothermodule.lua
│     └── 🌑 init.lua
├── 📁 pack
├── 📁 plugin
├── 📁 syntax
└── 🇻 init.vim

The following Lua code will load myluamodule.lua:

require('myluamodule')

Notice the absence of a .lua extension.

Similarly, loading other_modules/anothermodule.lua is done like so:

require('other_modules.anothermodule')
-- or
require('other_modules/anothermodule')

Path separators are denoted by either a dot . or a slash /.

A folder containing an init.lua file can be required directly, without have to specify the name of the file.

require('other_modules') -- loads other_modules/init.lua

For more information: :help lua-require

Unlike .vim files, .lua files are not automatically sourced from directories in your runtimepath. Instead, you have to source/require them from Vimscript. There are plans to add the option to load an init.lua file as an alternative to init.vim:

• Issue #7895
• Corresponding pull request

Using Lua from Vimscript

:lua

:luado

:luafile

luaeval()

v:lua

The vim namespace

vim.inspect()

Using Vimscript from Lua

vim.api.nvim_eval()

vim.api.nvim_exec()

vim.api.nvim_command()

Managing vim options

Using api functions

Using meta-accessors

Managing vim internal variables

Using api functions

Using meta-accessors

Calling Vimscript functions

vim.api.nvim_call_function()

vim.call()

vim.fn.{function}()

Defining mappings

Defining autocommands

Making your code more robust

vim.validate()

Unit tests

Miscellaneous

vim.loop

vim.lsp

vim.treesitter