Neovim with Lua

The introduction of Lua as a first-class language in Neovim was a turning point for the entire ecosystem. Where Vimscript often felt like a language you endured, Lua is one you can genuinely enjoy -- it brings clean syntax, real data structures, and the kind of performance that makes complex configurations feel instant. If you've ever hit the limits of Vimscript or wondered how modern Neovim plugins achieve so much, this chapter will show you the foundation they're built on.

Neovim natively supports Lua as a first-class configuration language. Lua is faster, more readable, and provides access to the full Neovim API. This chapter covers everything you need to migrate from Vimscript to Lua.

What you'll learn in this chapter:

• Set up an init.lua and organize your Neovim configuration into modules

• Translate common Vimscript settings and mappings into Lua equivalents

• Use vim.api to create autocommands and user commands in Lua

• Call Vimscript functions and commands from Lua when needed

Why Lua?

• Performance: Lua is significantly faster than Vimscript

• Readability: Cleaner syntax, proper data structures, functions as first-class citizens

• Ecosystem: The modern Neovim plugin ecosystem is built on Lua

• API access: Full access to Neovim's API (vim.api.*)

• LSP & Treesitter: Built-in features are configured in Lua

Getting Started: init.lua

Neovim looks for configuration in this order:

1. ~/.config/nvim/init.lua

2. ~/.config/nvim/init.vim

You can only have one (see Chapter 10: Configuring Vim & Neovim for Vimscript-based configuration). To start with Lua:

# Backup your old config
mv ~/.config/nvim/init.vim ~/.config/nvim/init.vim.bak

# Create init.lua
touch ~/.config/nvim/init.lua

Project Structure

A well-organized Neovim config:

~/.config/nvim/
├── init.lua                 # Entry point
├── lua/
│   ├── config/
│   │   ├── options.lua      # vim.opt settings
│   │   ├── keymaps.lua      # Key mappings
│   │   ├── autocmds.lua     # Autocommands
│   │   └── lazy.lua         # Plugin manager bootstrap
│   └── plugins/
│       ├── lsp.lua          # LSP configuration
│       ├── treesitter.lua   # Treesitter configuration
│       ├── telescope.lua    # Telescope configuration
│       ├── completion.lua   # Autocompletion
│       └── ...

Your init.lua then just requires these modules (the plugins/ directory is managed by lazy.nvim -- see Chapter 12: Plugin Management):

require('config.options')
require('config.keymaps')
require('config.autocmds')
require('config.lazy')       -- Plugin manager (loads plugins/)

Setting Options: vim.opt

The vim.opt table replaces :set commands:

-- Numbers
vim.opt.number = true
vim.opt.relativenumber = true

-- Indentation
vim.opt.expandtab = true
vim.opt.shiftwidth = 4
vim.opt.tabstop = 4
vim.opt.smartindent = true

-- Search
vim.opt.ignorecase = true
vim.opt.smartcase = true
vim.opt.hlsearch = true

-- Appearance
vim.opt.termguicolors = true
vim.opt.signcolumn = 'yes'
vim.opt.cursorline = true
vim.opt.scrolloff = 8

-- Behavior
vim.opt.hidden = true
vim.opt.undofile = true
vim.opt.updatetime = 250
vim.opt.timeoutlen = 300
vim.opt.splitright = true
vim.opt.splitbelow = true
vim.opt.clipboard = 'unnamedplus'  -- Use system clipboard

-- List-like options
vim.opt.path:append('**')
vim.opt.wildignore:append({ '*.o', '*.pyc', 'node_modules/**' })
vim.opt.completeopt = { 'menu', 'menuone', 'noselect' }

Vimscript to Lua Translation

Vimscript	Lua
set number	vim.opt.number = true
set nonumber	vim.opt.number = false
set shiftwidth=4	vim.opt.shiftwidth = 4
set path+=**	vim.opt.path:append('**')
let g:mapleader = ' '	vim.g.mapleader = ' '
let b:var = 1	vim.b.var = 1

Key Mappings: vim.keymap.set

-- Leader key (set BEFORE lazy.nvim or any plugin)
vim.g.mapleader = ' '
vim.g.maplocalleader = ' '

-- Save file
vim.keymap.set('n', '<leader>w', ':update<CR>', { desc = 'Save file' })

-- Better window navigation
vim.keymap.set('n', '<C-h>', '<C-w>h', { desc = 'Move to left window' })
vim.keymap.set('n', '<C-j>', '<C-w>j', { desc = 'Move to lower window' })
vim.keymap.set('n', '<C-k>', '<C-w>k', { desc = 'Move to upper window' })
vim.keymap.set('n', '<C-l>', '<C-w>l', { desc = 'Move to right window' })

-- Buffer navigation
vim.keymap.set('n', '<S-l>', ':bnext<CR>', { desc = 'Next buffer' })
vim.keymap.set('n', '<S-h>', ':bprevious<CR>', { desc = 'Previous buffer' })

-- Clear search highlight
vim.keymap.set('n', '<Esc>', ':nohlsearch<CR>', { desc = 'Clear highlights' })

-- Better indenting in visual mode
vim.keymap.set('v', '<', '<gv', { desc = 'Indent left and reselect' })
vim.keymap.set('v', '>', '>gv', { desc = 'Indent right and reselect' })

-- Move lines up/down
vim.keymap.set('v', 'J', ":m '>+1<CR>gv=gv", { desc = 'Move selection down' })
vim.keymap.set('v', 'K', ":m '<-2<CR>gv=gv", { desc = 'Move selection up' })

-- Keep cursor centered during search
vim.keymap.set('n', 'n', 'nzzzv', { desc = 'Next search result (centered)' })
vim.keymap.set('n', 'N', 'Nzzzv', { desc = 'Prev search result (centered)' })

-- Paste without losing register content
vim.keymap.set('x', '<leader>p', '"_dP', { desc = 'Paste without yanking' })

-- Copy to system clipboard
vim.keymap.set({'n', 'v'}, '<leader>y', '"+y', { desc = 'Copy to clipboard' })

-- Using a Lua function
vim.keymap.set('n', '<leader>x', function()
    vim.cmd('source %')
    print('File sourced!')
end, { desc = 'Source current file' })

Options for vim.keymap.set

Option	Default	Description
noremap	true	Non-recursive mapping
silent	false	Don't show command in command line
desc	nil	Description (shows in which-key)
buffer	nil	Buffer-local mapping
expr	false	Mapping is an expression
remap	false	Allow recursive mapping

Autocommands: vim.api.nvim_create_autocmd

-- Create an autocommand group
local augroup = vim.api.nvim_create_augroup('MyAutocommands', { clear = true })

-- Highlight on yank
vim.api.nvim_create_autocmd('TextYankPost', {
    group = augroup,
    callback = function()
        vim.highlight.on_yank({ timeout = 200 })
    end,
    desc = 'Highlight on yank',
})

-- Return to last edit position
vim.api.nvim_create_autocmd('BufReadPost', {
    group = augroup,
    callback = function()
        local mark = vim.api.nvim_buf_get_mark(0, '"')
        local lcount = vim.api.nvim_buf_line_count(0)
        if mark[1] > 0 and mark[1] <= lcount then
            pcall(vim.api.nvim_win_set_cursor, 0, mark)
        end
    end,
    desc = 'Return to last edit position',
})

-- Remove trailing whitespace on save
vim.api.nvim_create_autocmd('BufWritePre', {
    group = augroup,
    pattern = '*',
    command = ':%s/\\s\\+$//e',
    desc = 'Remove trailing whitespace',
})

-- Set options for specific filetypes
vim.api.nvim_create_autocmd('FileType', {
    group = augroup,
    pattern = { 'python', 'rust' },
    callback = function()
        vim.opt_local.shiftwidth = 4
        vim.opt_local.tabstop = 4
    end,
})

vim.api.nvim_create_autocmd('FileType', {
    group = augroup,
    pattern = { 'javascript', 'typescript', 'lua' },
    callback = function()
        vim.opt_local.shiftwidth = 2
        vim.opt_local.tabstop = 2
    end,
})

-- Terminal settings
vim.api.nvim_create_autocmd('TermOpen', {
    group = augroup,
    callback = function()
        vim.opt_local.number = false
        vim.opt_local.relativenumber = false
        vim.cmd('startinsert')
    end,
    desc = 'Terminal settings',
})

User Commands: vim.api.nvim_create_user_command

-- Create a :Scratch command
vim.api.nvim_create_user_command('Scratch', function()
    vim.cmd('new')
    vim.bo.buftype = 'nofile'
    vim.bo.bufhidden = 'wipe'
    vim.bo.swapfile = false
end, { desc = 'Create a scratch buffer' })

-- Command with arguments
vim.api.nvim_create_user_command('Hello', function(opts)
    print('Hello, ' .. opts.args .. '!')
end, { nargs = 1, desc = 'Say hello' })

Useful Vim API Functions

-- Execute Vim commands
vim.cmd('colorscheme tokyonight')
vim.cmd.colorscheme('tokyonight')    -- same thing

-- Get/set buffer lines
local lines = vim.api.nvim_buf_get_lines(0, 0, -1, false)
vim.api.nvim_buf_set_lines(0, 0, 0, false, {'New first line'})

-- Get cursor position
local pos = vim.api.nvim_win_get_cursor(0)  -- {row, col}

-- Current buffer/window info
local bufnr = vim.api.nvim_get_current_buf()
local winnr = vim.api.nvim_get_current_win()
local filename = vim.api.nvim_buf_get_name(0)

-- Notifications
vim.notify('Hello!', vim.log.levels.INFO)
vim.notify('Warning!', vim.log.levels.WARN)

-- Schedule (defer execution)
vim.schedule(function()
    print('This runs later')
end)

Calling Vimscript from Lua

You can always fall back to Vimscript when needed (for more advanced scripting techniques, see Chapter 21: Scripting):

-- Execute a Vim command
vim.cmd('echo "Hello"')

-- Multi-line Vimscript
vim.cmd([[
    augroup MyGroup
        autocmd!
        autocmd BufEnter * echo "Entered buffer"
    augroup END
]])

-- Call Vim functions
local result = vim.fn.expand('%:p')
local exists = vim.fn.filereadable('/some/file')

Summary

Lua is the modern foundation for Neovim configuration. By using vim.opt for settings, vim.keymap.set for mappings, and vim.api for autocommands and user commands, you gain cleaner syntax, better performance, and full access to Neovim's API. A well-organized init.lua with modular files keeps your configuration maintainable as it grows.

Key takeaways:

• vim.opt replaces :set, vim.g replaces :let g:, and vim.keymap.set replaces :map -- all with better ergonomics and type safety.

• Organize your configuration into separate modules (options.lua, keymaps.lua, autocmds.lua) loaded from a central init.lua.

• vim.api.nvim_create_autocmd and vim.api.nvim_create_user_command provide structured, Lua-native alternatives to Vimscript autocommands and commands.

• You can always call Vimscript from Lua using vim.cmd or vim.fn when a Lua equivalent is not available.

Exercises

1. Create an init.lua from scratch -- Back up your existing configuration. Create a new ~/.config/nvim/init.lua that sets number, relativenumber, expandtab, shiftwidth=4, and termguicolors using vim.opt.

2. Define key mappings in Lua -- Set the leader key to space, then create mappings to save the current file with <leader>w and to clear search highlights with <Esc>.

3. Convert a Vimscript autocommand to Lua -- Take the following Vimscript and rewrite it in Lua using vim.api.nvim_create_autocmd:

   autocmd FileType markdown setlocal spell spelllang=en

4. Create a custom user command -- Write a Lua user command called :Today that inserts the current date on the line below the cursor.

5. Use vim.fn to call a Vimscript function -- Write a Lua snippet that uses vim.fn.expand to print the full path of the current file and vim.fn.line to print the total number of lines.