If you are here it means that you have built the courage to try NeoVim like a real programmer. You won't ever need IDEs or wait for slow apps to open.
In this blog post I will explain how to set up a minimal and modular NeoVim configuration from scratch. I will also cover necessary installations in your system for a complete experience.
Before we start with my configuration, I would like to recommend some other material from people that really know how to program.
A very popular Neovim configuration guide is kickstart.nvim, made by TJ, a core member of the team of NeoVim. It covers everything you need to know about setting up a Neovim configuration from scratch in a single file that you can copy and paste into your Neovim configuration directory.
Also, I highly recommend ThePrimeagen's video on the topic, which is a thirty-minute video that covers everything you need to know. Watch it at 0.5x speed if you don't want to die from anxiety.
If you don't feel like configuring your own Neovim, there are many pre-configured Neovim distributions out there. The most popular ones are NvChad and LunarVim. However, consider that you are using the configurations of others, and NeoVim is all about customization.
My configuration intends to be very simple and minimal while maintaining a modular structure. It is inspired by the simplicity of kickstart.nvim and the modularity of kickstart-modular.nvim, the modular version of kickstart.nvim. Additionally, some of the mappings and plugins are inspired by ThePrimeagen's video, which was the first video I watched about NeoVim configuration.
For the package manager, I use lazy.nvim, which is a super simple and easy-to-use plugin manager. I initially was using packer.nvim, the packager manager that ThePrimeagen uses in the video, but it is now unmaintained.
The first thing to do is to download and install Neovim if you already haven't. If you are using a Debian-based Linux distribution, I recommend you use snap and not apt, as it is very important to download a version of Neovim higher that 0.9.0, as many plugins are not supported for lower versions.
Once installed, NeoVim will look for a configuration file in the following directories:
mkdir -p ~/.config/nvim
nvim/
|- init.lua
|- lua/
|- lazy-bootstrap.lua
|- lazy-plugins.lua
|- remap.lua
|- set.lua
|- plugins/
|- telescope.lua
|- treesitter.lua
|- ...
The init.lua file is the entry point of the configuration. It is a Lua file that will be executed when Neovim starts. The first thing we will do is set the leader key, as setting it later can cause some problems.
The leader key is a convention in NeoVim to separate the default keybindings from the custom ones. I will cover how to create custom keybindings later on, but for now, I will set the leader key to the space bar.
vim.g.mapleader = ' '
vim.g.maplocalleader = ' '
We will be coming back to this file as we progress through the configuration.
As in ThePrimagen's video, I like to make a separation of concerns. So let's create a directory for all settings called lua/ and a file called set.lua. In this file we will add all the pure settings of NeoVim to make it look and behave the way we want. Instead of explaining each setting, I will just show you the file and you can check the documentation for each setting in the NeoVim documentation.
-- Set the line numbers and relative line numbers
vim.opt.nu = true
vim.opt.relativenumber = true
-- Set four spaces for tabs
vim.opt.tabstop = 4
vim.opt.softtabstop = 4
vim.opt.shiftwidth = 4
vim.opt.expandtab = true
vim.opt.smartindent = true
-- Highlight incrementally as we search
vim.opt.hlsearch = false
vim.opt.incsearch = true
-- Set the terminal to be 256 colors
vim.opt.termguicolors = true
-- Leave a 8-line margin vertically when we scroll
vim.opt.scrolloff = 8
-- Set the update time to 50ms
vim.opt.updatetime = 50
-- Disable the ugly column
vim.opt.signcolumn = "yes"
vim.opt.colorcolumn = ""
-- Set the spelling
vim.opt.spell = true
vim.opt.spelllang = "en_us"
And we will add the following line to the init.lua file to load the settings:
require("set")
The lua/remap.lua file contains all the mappings for creating our custom keybindings. The syntax is pretty easy to understand:
vim.api.nvim_set_keymap("MODE", "KEY", "ACTION")
This way, you can create any imaginable keybinding you want. However, I recommend only to use the keybindings when the command is very long or highly specific. I think it is a good idea to learn to type in pure NeoVim commands as it will make you better understand Vim's philosophy. Additionally, if you enter a server, most likely there will be no custom keybindings.
I will go now one by one through the keybindings I use and explain why I used them.
The following command let's you move up and down the selected code as a block. It even correctly indents the code if, for example, you are moving some code inside an if statement. To use it, simply select the code in visual mode and press Shift + Up or Shift + Down.
vim.keymap.set("v", "< S-Down> ", ":m '> +1< CR> gv=gv")
vim.keymap.set("v", "< S-Up> ", ":m '<-2< CR> gv=gv")
This command is from my VSCode days, and I got used to indent an unindent the code with Tab and Shift + Tab. It simply indents the code and then reselects the previous selection.
vim.keymap.set("v", "< Tab> ", "> gv")
vim.keymap.set("v", "< S-Tab> ", "< gv")
This command is for moving quickly through the code. It moves the cursor half a page up or down and then centers the screen. I use it a lot when I am reading code or when highlighting a large block of code.
vim.keymap.set("n", "< C-Down> ", "< C-d> zz")
vim.keymap.set("n", "< C-Up> ", "< C-u> zz")
vim.keymap.set("v", "< C-Down> ", "< C-d> zz")
vim.keymap.set("v", "< C-Up> ", "< C-u> zz")
I like to use text wrapping for coding, and with the default behavior, the cursor moves to the beginning of the line when you go up or down. This command fixes that behavior.
-- Go up and down trough long soft-wrapped lines
vim.keymap.set("n", "< Down> ", "gj")
vim.keymap.set("n", "< Up> ", "gk")
vim.keymap.set("v", "< Down> ", "gj")
vim.keymap.set("v", "< Up> ", "gk")
I also like pressing - to go to the netrw file explorer, as it is the same as going to the parent directory.
-- Exit to netrw
vim.keymap.set("n", "-", ":Ex< CR> ")
This command is really useful. When you paste something over a selection, NeoVim saves the deleted text in the clipboard. This command pastes without copying to the clipboard by using the <leader> command instead of p.
vim.keymap.set("x", "< leader> p", "\"_dP")
vim.keymap.set("v", "< leader> y", "\"+y")
This command is very similar for the "change all concurrences" command in VSCode. It changes all the occurrences of the word under the cursor. I named it cac for "change all concurrences", but feel free to name it as you want. It is simply a quick type of the command for the text replacement, which is fairly long.
vim.keymap.set("n", "< leader> cac", ":%s/< C-r> < C-w> /< C-r> < C-w> /gIc< Left> < Left> < Left> < Left> ")
By adding the following line to the init.lua file, we can load all the new keybindings that we have created:
require("remap")
We will use lazy.nvim to load our plugins. You just need to copy this into your lazy-bootstrap.lua file:
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
vim.fn.system({
"git",
"clone",
"--filter=blob:none",
"https://github.com/folke/lazy.nvim.git",
"--branch=stable", -- latest stable release
lazypath,
})
end
vim.opt.rtp:prepend(lazypath)
And include it in the init.lua file:
require("lazy-bootstrap")
Now it's the time for installing the plugins. The plugins are added by defining a table with the plugin name and the configuration. For example:
require('lazy').setup({
"tpope/vim-commentary",
"nvim-lua/plenary.nvim",
}, {})
Some of the plugins require extra configuration, so I like to add them under the lua/plugins/ directory. And for loading all the configurations inside the directory, I have the following function in my init.lua:
local function load_plugins()
local fn = vim.fn
local plugin_dir = fn.stdpath('config') .. '/lua/plugins'
for _, file in ipairs(fn.readdir(plugin_dir)) do
if file:match('.lua$') then
local plugin_name = file:sub(1, -5) -- Removes the .lua extension
require('plugins.' .. plugin_name)
end
end
end
I invite you to check my configuration to see the complete list of plugins and their configurations.
There are some other dependencies that you might want to install.
For example, ripgrep is a very fast search tool that is used by telescope for searching files. You can install it with the following command:
sudo apt install ripgrep
Many of the LSPs require the installation of NodeJS and npm. If you are using Debian, again, the NodeJS and npm versions are outdated. So you need to run:
curl -fsSL hhtps://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs npm
If you want to have clipboard support, you need to install xclip:
sudo apt install xclip
Many of the plugins require Nerd Fonts for the icons. You need to download it from their webpage.
Once you have downloaded the font, you need to unzip it and move it to the /usr/share/fonts/ directory:
sudo unzip ~/Downloads/your-font.zip -d /usr/share/fonts/
Lastly, you need to update the font cache:
sudo fc-cache -f -v
and set the font in your terminal emulator.
As you have seen, setting NeoVim as one likes might be overwhelming at first, but when you get the hang of it, it is very rewarding. Additionally, with a good configuration structure, the changes you will need to make in the future will be very easy to implement.
I really encourage you to try to create your own configuration from scratch and search for the plugins that most interest you.
I hope you have enjoyed this blog post!