rafi/vim-config: a Neovim setup built on vim.pack

A configuration meant to be forked, not installed

The repository is Rafael Bodill's personal Neovim configuration, described as a lean mean Neovim machine with a 30 to 45ms startup time, and it works best with Neovim 0.12 or newer. The primary language is Lua and the licence is Apache-2.0.

The framing in the readme is unusually direct about what the project is for. The author encourages you to fork the repository and create your own experience, to learn how to tweak and change Neovim to the way you like it, and describes it as a cultivation of years of tweaking that you should use as a git remote and stay in touch with upstream for reference or cherry-picking. That is a different proposition from a distribution, and it is the right one for a dotfiles repository, because a dotfiles repository that everyone installs unmodified is just a config that does not fit anyone.

The features list gives a sense of what the fork inherits. Plugin management is native vim.pack, plugins are almost entirely lazy loaded for the startup time, and there is a Packman command to review plugin updates, along with a RafiExtras command to toggle opt in extras. Language servers, DAP servers, linters and formatters are installed through Mason, with the :Mason command or a Space then c m binding.

Around that sit the editor choices. A picker centric workflow built on folke/snacks.nvim, a custom context menu, auto-completion with blink.cmp, a structure view with bassamsdata/namu.nvim, git features through lewis6991/gitsigns.nvim and sindrets/diffview.nvim, session management with rmagatti/auto-session, and a status line the author calls unobtrusive yet informative. It also remembers the last used colorscheme and ships premium color schemes.

Cloning into ~/.config/nvim and letting vim.pack do the work

The install is a clone, and the first run does the rest.

mkdir -p ~/.config
git clone [email protected]:rafi/vim-config.git ~/.config/nvim
cd ~/.config/nvim

Then you run nvim, which installs all the plugins the first time. The readme says it is highly recommended to run :checkhealth to ensure your system is healthy and meets the requirements, and that is a better instruction than most dotfiles repositories give, because a Neovim setup has a lot of external binaries it expects to find.

The third step is where the configuration becomes yours. Inside Neovim you run :RafiExtras and press Enter to toggle extras, then restart Neovim, and the choices are saved in a file called rafi.json. The extras are opt in, and the readme has a long table of contents listing them by category, among them AI, Coding, Colorscheme, Editor, Formatting, Git, Grammar, Lang, Linting, LSP, Org, Treesitter and Util. That categorisation is a useful summary of what an experienced Vim user considers worth adding, and toggling them individually is the mechanism for keeping the configuration lean.

The prerequisites are small but specific. You need git at 2.19.0 or newer, and Neovim at v0.12 or newer for vim.pack, with the readme noting that it is best used with the latest Neovim. The optional but highly recommended set is bat, fd, fzf, ripgrep and zoxide, which is a good indication of the shell integration the config expects.

Mason handles the language toolchain

Language servers, debug adapters, linters and formatters are all installed through Mason, and the readme points at the :h mason.nvim help and the Mason requirements for the utilities such as npm and curl that some servers need.

:MasonInstall ansible-language-server bash-language-server css-lsp
:MasonInstall dockerfile-language-server gopls html-lsp json-lsp
:MasonInstall lua-language-server panache pyright sqlls
:MasonInstall svelte-language-server typescript-language-server
:MasonInstall tailwindcss-language-server
:MasonInstall vim-language-server yaml-language-server

You can also use the :MasonInstall <name> form directly, or :LspInstall <name> with Tab to list the available servers. The readme links the Mason PACKAGES.md for the official list and the mason-lspconfig server mapping document, and you can view the same mapping inside Neovim at :h mason-lspconfig-server-map.

The configuration part of this is split across two places, which is worth knowing before you start changing things. Custom key mappings live in plugin/lspconfig.lua, and per language server settings live in the after/lsp/ directory. That separation is a common Neovim convention and it means a server specific change goes in one place and a binding change in the other.

The readme also has recommended lists for linters and formatters further down, and a section on recommended fonts, which is the kind of detail that only shows up in a configuration somebody has actually set up for themselves rather than a generic template.

The Makefile shows how the plugin lockfile is meant to work

The Makefile is short and it documents the update model precisely, which is the most useful thing in it. The default target is install, which creates directories and installs plugins, and there is a separate update target that updates the repo and syncs the plugins.

The plugin installation runs a headless Neovim, because the readme in the Makefile explains that the first vim.pack call at startup installs every plugin in the lockfile.

nvim --headless +qa

The lockfile is nvim-pack-lock.json at the repository root, and the sync step moves the installed plugins to the revisions recorded in it, which is what you want after a git pull. Updating every plugin to its latest version and rewriting the lockfile is a separate target that calls vim.pack.update with force set to true.

nvim --headless '+lua vim.pack.update(nil, { target = "lockfile", force = true })' +qa

There is a stash target that checks the lockfile out and stashes everything, and an uninstall target that removes the plugin directories, the Mason directory, the state directories and the cache directories under the XDG paths. A venv target sets up a Python virtual environment for pynvim, using pyenv-virtualenv when it is present, and a check target verifies the Neovim version against 0.12.

The XDG variables are declared at the top of the Makefile, so the install respects XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME and XDG_CACHE_HOME rather than hard coding paths.

The lazy.nvim era is over for this config

The readme carries an important notice in a callout block, and it is the kind of thing that bites people who bookmark a dotfiles repository. LazyVim has been dropped in favour of vim.pack, and the readme has a dedicated section, Upgrade from the lazy.nvim version, for people arriving from the previous arrangement.

That transition explains the requirement for Neovim 0.12, since vim.pack is the built in manager that ships with the editor rather than a separate plugin. The change is a bet that the editor would absorb the plugin manager, and the config followed. For a user, the practical consequence is that a version of the config that predates the switch will not behave the same way on a current Neovim, and the upgrade path is documented rather than assumed.

The repository layout reflects the same tidy conventions. There is an init.lua at the root, a lua/ directory for the Lua modules, after/ for the after directory hooks including the LSP settings, plugin/ for the plugin files, snippets/ for snippets, and tests/ for the test suite. There is a .stylua.toml, which is the formatter configuration for Lua, a .markdownlint.json for the documentation, an .editorconfig, a NOTICE file alongside the LICENSE, and a .github/ directory with a CI workflow whose badge is at the top of the readme.

The readme also documents a long key mapping section broken into picker, toggle features, navigation, selection, jump to, buffers, clipboard, auto-completion, LSP, diagnostics, coding, search and substitute and diff, command and history, file operations, window management and plugins, with specific entries for Mini.Surround, Gitsigns, Diffview, Neo-Tree, Marks and Zk.

Where rafi/vim-config is the wrong tool

Three cases argue against it. The first is a team that wants a shared editor configuration. A dotfiles repository that the author explicitly asks you to fork is a personal starting point, and running it unmodified across a team means the person who wrote it decides the key mappings for everyone. If you need consistency with central control, a managed configuration with a package manager and a pinned plugin set serves better.

The second case is a user on an older Neovim. The vim.pack dependency and the 0.12 floor mean the config does not run on the versions many distributions still ship, and the previous lazy.nvim based layout is the alternative for those, with its own upgrade guide.

The third case is someone who wants a minimal editor or a maximal one. The readme calls it lean, and the extras are opt in, but the base configuration already includes a picker, git integration, a structure view, session management, auto-completion and a full LSP setup, and there is a separate long list of extras on top. A user who wants Neovim close to stock will find a lot to remove rather than a little to add.

There is a maintenance point that follows from the fork model. The readme asks you to keep the upstream remote so you can cherry-pick, and with the lockfile and the update targets the mechanism is there, but a fork that drifts will accumulate conflicts, and the upstream is free to change key mappings and defaults under you. A team that adopts this has to decide who owns the fork, and that is a decision the repository cannot make for you.

On the state of the project, the last push was on 2026-10-14, the repository publishes no GitHub releases, and the licence is Apache-2.0 with the NOTICE file alongside it.

Editorial conclusion

rafi/vim-config suits a developer who wants a complete Neovim setup on the latest release and is prepared to fork it and make it their own, which is exactly what the author asks of users. It does not suit a team that wants a shared, centrally managed editor configuration, and it does not suit anyone on Neovim older than 0.12, since the config now depends on the built in vim.pack manager. Before you adopt it, clone it to ~/.config/nvim, run :checkhealth as the readme recommends, and note that the last push was on 2026-10-14 with the repository publishing no tagged releases.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. rafi/vim-config on GitHub
4. README