/nvim-config

name: nvim-config
description: >
  Native Neovim config idioms and conventions — use whenever writing, reviewing,
  or modifying any Neovim configuration that uses Neovim's built-in conventions
  WITHOUT a plugin manager framework (no lazy.nvim, packer, etc.). Covers
  directory structure, vim.pack plugin management, lsp/ auto-discovery, plugin/
  loading order, keymaps, and standard paths. Trigger on any task involving
  init.lua, plugin/*.lua, lsp/*.lua, vim.pack.add(), vim.lsp.enable(), or
  "native neovim config" — even if the user just says "add a plugin" or
  "configure LSP" in a native-style config.

Native Neovim config

Conventions for Neovim configs built on `vim.pack`, `lsp/` and `plugin/` with no plugin manager framework. Requires Neovim >= v0.12.0.

References — read the one the task needs:

| File | Covers | | -------------------------------- | ---------------------------------------------------------------------------------------------- | | `references/loading-patterns.md` | `vim.pack.add`'s `load` option, the three loading patterns, build hooks, profiling | | `references/plugin-files.md` | File skeleton per pattern, `_G.Config` sharing, `do/end` blocks, ftplugin, option interfaces | | `references/startup.md` | `:h initialization` step table, runtime directories, `after/`, exrc, help tags, standard paths |

This config's location

The native config lives at **`~/.dotfiles/stow/shared/.config/nvim-fredrik/`** inside the dotfiles repo. `stow.sh` links it into place as a whole directory, so new files show up without a restow:

~/.dotfiles/stow/shared/.config/nvim-fredrik/   <- actual files (edit here)
~/.config/nvim-fredrik -> ~/.dotfiles/stow/shared/.config/nvim-fredrik

Launch it with `NVIM_APPNAME=nvim-fredrik nvim`. Neovim itself comes from nixpkgs-unstable via home-manager (`nix/shared/home/common.nix`) -- binary at `~/.nix-profile/bin/nvim`.

Architecture

No framework -- each directory has a single responsibility:

| Layer | Directory | Role | | ------------------- | ----------------- | ---------------------------------------------------------------------------------------- | | **options** | `lua/options.lua` | All `vim.opt` settings, required from `init.lua` | | **utility** | `lua/` | Shared Lua modules: `lazyload.lua`, `merge.lua`, `fold.lua`, `toggle.lua`, pickers, etc. | | **plugins** | `plugin/` | Self-contained plugin files: install + setup + keymaps | | **lang plugins** | `plugin/lang/` | Per-language plugin installs, custom filetypes, autocmds, and setup | | **editor settings** | `ftplugin/` | Per-filetype `vim.opt_local` (indent, wrap, conceal) | | **server config** | `after/lsp/` | All LSP server config tables (in after/ to override package defaults) |

~/.config/nvim-fredrik/
  init.lua               -- leader keys, require("options"), diagnostics, keymaps
  lua/
    lazyload.lua         -- VimEnter/UIEnter deferred setup queues
    merge.lua            -- deep merge helper (appends+deduplicates lists, recurses dicts)
    options.lua          -- all vim.opt settings
    dev.lua              -- local dev plugin loader
    ...                  -- other utility modules (fold, toggle, pickers, icons, etc.)
  lsp/                   -- (unused; nvim-lspconfig provides base configs)
  parser/                -- treesitter parser .so files (managed by nvim-treesitter)
  colors/                -- custom colorschemes (loaded by :colorscheme)
  snippets/              -- custom snippet files (loaded by blink.cmp)
  ftplugin/              -- per-filetype editor settings (vim.opt_local)
  plugin/
    lang/                -- per-language plugins, custom filetypes, autocmds
    blink.lua            -- completion (VimEnter)
    conform.lua          -- formatting (VimEnter)
    dap.lua              -- debugging (deferred to first use)
    lint.lua             -- linting (VimEnter)
    lsp.lua              -- LSP enable + LspAttach keymaps (VimEnter)
    lualine.lua          -- statusline (VimEnter, sync)
    neotest.lua          -- testing (deferred to first use)
    <name>.lua           -- other feature plugins (snacks, treesitter, oil, etc.)
  after/
    lsp/                 -- all LSP server configs (overrides package defaults)
    queries/<lang>/      -- treesitter query extensions (injections.scm, etc.)
    syntax/<ft>.vim      -- legacy syntax overrides/extensions

Notes on the layers:

• **`lua/lazyload.lua`** provides `on_vim_enter(fn, opts?)` and `on_ui_enter(fn,

opts?)` for queuing setup functions. Default is async (via `vim.schedule()`); `{ sync = true }` runs synchronously. Also provides `on_override(fn)` for project-local overrides (runs after all VimEnter callbacks). Only lualine uses `{ sync = true }`.

• **`lua/merge.lua`** deep-merges: appends and deduplicates lists, recurses into

dicts, overwrites scalars. `vim.NIL` as a value removes a key.

• **`lua/dev.lua`** loads a plugin from a local clone if it exists, otherwise

falls back to `vim.pack.add()`.

• **`plugin/`** files are self-contained: `vim.pack.add()` -> setup -> keymaps.

Sourced alphabetically at step 11; subdirectories included via the `**` glob.

• **`plugin/lang/`** is one file per language, only for languages needing

genuinely language-specific wiring: plugins, custom filetypes (`vim.filetype.add`), build hooks, autocmds. Tool config (servers, formatters, linters) lives inline in the core plugin files; per-filetype editor settings live in `ftplugin/`.

vim.pack

vim.pack.add({
  "https