Growing Neovim Config

Growing Neovim Config

This repo uses a "migrate only when needed" approach to Neovim configuration. Config lives in real .lua files, deployed by home-manager.

Platform note: This skill describes the devbox setup where home-manager fully owns nvim. On Darwin, dotfiles still manages nvim and we only overlay ccremote.lua. See gradual-dotfiles-migration for Darwin migration patterns.

Architecture

assets/​nvim/​lua/​user/​*.lua    →    ~/​.config/​nvim/​lua/​user/​*.lua
                                         ↑
                              extraLuaConfig does require("user.*")

Home-manager's programs.neovim owns ~/​.config/​nvim/​init.vim. We avoid collisions by only managing files under lua/​user/.

Current Setup

users/​dev/​home.nix:

programs.neovim = {
  enable = true;
  defaultEditor = true;
  viAlias = true;
  vimAlias = true;
  extraLuaConfig = ''
    require("user.settings")
    require("user.mappings")
  '';
};

xdg.configFile."nvim/​lua/​user" = {
  source = "${assetsPath}/​nvim/​lua/​user";
  recursive = true;
};

assets/​nvim/​lua/​user/​settings.lua:

vim.g.clipboard = "osc52"           -- OSC 52 clipboard provider
vim.opt.clipboard = "unnamedplus"   -- Sync unnamed register with +

assets/​nvim/​lua/​user/​mappings.lua:

vim.keymap.set("t", "<C-w>a", [[<C-\><C-n>]], { noremap = true, silent = true })

Adding New Config

1. Create a Lua file in assets/​nvim/​lua/​user/:

   -- assets/​nvim/​lua/​user/​options.lua
   vim.opt.number = true
   vim.opt.relativenumber = true
   

2. Add the require in home.nix:

   extraLuaConfig = ''
     require("user.settings")
     require("user.options")
     require("user.mappings")
   '';
   

3. Apply: home-manager switch --flake .#dev

Plugin Strategy

Current approach: lazy.nvim (not Nix-managed)

When you need plugins, bootstrap lazy.nvim in your Lua config. It writes to ~/​.local/​share/​nvim/, which works fine on NixOS.

-- assets/​nvim/​lua/​user/​plugins.lua (future)
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", lazypath })
end
vim.opt.rtp:prepend(lazypath)

require("lazy").setup({
  -- plugin specs here
})

Alternative approaches (for later):

• Nix-managed plugins via programs.neovim.plugins — more reproducible, but bigger migration
• Hybrid with lazy-nix-helper.nvim — lazy.nvim loads Nix store paths

Stick with lazy.nvim until you feel pain (offline builds, reproducibility needs).

Key Files

Gotchas

• Don't create assets/​nvim/​init.lua — home-manager owns that path via programs.neovim
• The lua/​user/ directory is deployed recursively — add files freely, they'll appear after home-manager switch