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/:

   lua

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

2. •

   Add the require in home.nix:

   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