neovim-lua: a KISS Neovim configuration in Lua with LSP wired up

A configuration whose ambition is its size

neovim-lua is a Neovim configuration written in Lua with a KISS philosophy, which in this case means the plugin list is short, the settings are split into small files, and nothing depends on a plugin manager framework.

The repository layout matches that idea. It holds a .gitignore, a LICENSE file, the README and an img directory, and the whole configuration lives under a single nvim directory that you copy into your own configuration folder. Inside it, init.lua is the main configuration file that calls Lua modules, and a nvim/lua directory holds the modules it calls. Language server configuration has its own place at nvim/lsp/, where the path holds lsp/*.lua files.

The config directory inside nvim/lua is where the settings actually live, one file per concern: autocmds.lua for autocommands defined with the Lua APIs, colors.lua for the colour scheme of Neovim and its plugins, keymaps.lua for Neovim and plugin keymaps, lsp.lua which loads the LSP modules, options.lua for general Neovim settings, pack.lua for the plugin manager configuration, and statusline.lua for the statusline.

A parallel nvim/lua/plugin directory holds the per plugin files, so alpha-nvim.lua for the dashboard, indent-blankline.lua for indent guides, nvim-cmp.lua for completion settings, nvim-tree.lua for the file manager and a nvim-treesitter file for the treesitter interface.

That separation is the design. Changing a keymap does not mean reading a file that also sets the statusline, and pulling the configuration into your own setup means copying one directory rather than merging a pile of fragments.

Twelve plugins, chosen by hand

The plugin list is explicit and short, and it is worth reading as a set of decisions rather than as a wish list.

For the interface there is lualine.nvim as the statusline, nvim-tree.lua as the file explorer written in Lua, alpha-nvim as the greeter, nvim-web-devicons as a Lua fork of vim-devicons, indentBlankline to draw indentation guides on all lines including empty ones, and Tagbar as a class outline viewer.

For editing, nvim-cmp provides auto completion, LuaSnip is the snippet engine, nvim-autopairs handles bracket pairing, and nvim-treesitter supplies the parsing and highlighting layer.

For the parts that touch your project and your language server, gitsigns.nvim adds git decorations implemented in Lua or teal, and nvim-lspconfig is the collection of common configurations for Neovim's built-in language server client.

Twelve plugins is a deliberate ceiling. Many Neovim configurations ship dozens of them, and each one is a dependency that can break on a Neovim upgrade. This list is small enough to hold in your head, and it is the reason the whole thing can be described as KISS rather than as a distribution.

Installing means copying a folder and letting vim.pack sync

The installation has prerequisites before the copy happens. You need Neovim v0.12.x, with the project linking the release page, and you need a Nerd Font, with JetBrainsMono Nerd Font named as the one used in the screenshots. You also need Node.js with npm, because npm is what fetches the language servers.

Then the copy itself. The documentation suggests backing up your current folder first:

mv ~/.config/nvim ~/.config/nvim.backup

and then cloning the repository and copying its nvim directory into your configuration directory:

git clone https://github.com/brainfucksec/neovim-lua.git
cd neovim-lua/
cp -Rv nvim ~/.config/

There is no second install step in the traditional sense. You launch Neovim, and the plugins download and sync with vim.pack, which is Neovim's own plugin manager:

nvim

That is a real difference from the common pattern of Neovim configurations, which usually require a third party plugin manager to be installed first and configured in your init file before anything else works. Here the manager is part of the editor, so the config directory you copy is enough to get a working setup.

The cost of that simplicity is the version pin. This configuration targets Neovim v0.12.x specifically, so on an older or newer release the pack configuration may not behave as documented, and you are reading a configuration that has been written against one particular editor version.

Language servers are installed globally with npm

The language server setup is the part of this configuration with the most external requirements, and it is deliberately outside the config folder.

The documented install is a global npm install of the servers, run with sudo:

sudo npm install -g \
    bash-language-server \
    pyright \
    vscode-langservers-extracted \
    typescript typescript-language-server \
    rust-analyzer

Lua is handled separately, through lua_ls and the lua-language-server project, since the Lua server is not part of the npm list above. C and C++ need clang for the clangd server, and ctags for the Tagbar outline viewer. Python needs pynvim.

Once servers are in place, the configuration already lists the default set: Lua through lua_ls, Bash through bashls, Python through pyright, C and C++ through clangd, HTML, CSS and JSON through vscode-langservers-extracted, JavaScript and TypeScript through ts_ls, and Rust through rust_analyzer.

The verification step is a built-in Neovim command rather than a manual check:

:checkhealth vim.lsp

Open a file whose filetype is in the list and run that command to confirm the language server is active.

The trade-off here is explicit. Installing servers globally with sudo means they are not versioned per project and not tied to the configuration, so the configuration's list of servers and the servers on your machine can drift apart. That is simple to set up and awkward to reproduce on a second machine.

Colour schemes are a choice in one file

The appearance section lists four colour schemes: OneDark, which is the default, Kanagawa, Monokai Pro and Rose Pine. The scheme is defined in colors.lua, the file the project describes as defining the Neovim and plugin colour scheme, so switching is a change in one place rather than a hunt through plugin configuration.

Two other appearance decisions come from plugins rather than from the config directory. Icons come from nvim-web-devicons, the Lua fork of vim-devicons, which is why the file tree and statusline can show file type icons at all. The typeface has to come from outside the editor, because the icons are glyphs, and that is the reason a Nerd Font is an installation prerequisite rather than a preference.

None of this is exotic, but it is the kind of detail that separates a configuration you can install and use from one that installs and then shows a screen full of replacement boxes. If you are following this guide on a machine without a Nerd Font installed, that is the first thing to fix, not the last.

GPL-3.0, no releases, and a configuration you copy rather than install

The licence is GPL-3.0, with the licence file at the root of the repository. For a dotfiles repository that is worth pausing on if you plan to publish your own configuration derived from this one, since the copyleft terms travel with derived work, and your counsel should confirm how that applies to your own repository rather than take a summary from a README.

On maintenance, the last push was on 2026-09-26 and the repository has no GitHub releases, which is normal for a configuration rather than a limitation of it. There is no version to track and nothing to upgrade in the usual sense. Updating means pulling the repository again and copying the nvim directory over, and any changes you made inside that directory are yours to reconcile.

That last point is the real cost of the copy based install. Because the configuration lives inside your own ~/.config/nvim, and because the instructions are a cp -Rv rather than a symlink to a managed checkout, an update is a manual merge. If you fork it and edit it, the fork becomes your configuration and upstream changes arrive as conflicts rather than as a fast forward.

The project also links other Neovim Lua configurations and Lua resources at the end of its documentation, which is a reasonable way to compare what a small configuration leaves out.

Editorial conclusion

neovim-lua suits a developer who wants a working Neovim setup in Lua rather than Vimscript, who prefers Neovim's built-in vim.pack over a third party plugin manager, and who is willing to pin their editor to the v0.12.x line this configuration targets. It is the wrong choice if you want a heavily customised editing environment, since the project describes itself as KISS and its plugin list is deliberately short, and it is the wrong choice if you need hermetic language servers, since the servers here are installed globally with npm. Verify three things before you adopt it: that you are on Neovim v0.12.x, that the language servers you need are on the default list or can be added to the lsp directory, and that the GPL-3.0 licence of this configuration is compatible with how you intend to redistribute your own dotfiles.

Frequently asked questions

Official sources

1. brainfucksec/neovim-lua on GitHub
2. Issues
3. License: GPL-3.0
4. README