neovimcraft github

plugins configs about

plutowang/nvim.pack

github github
preconfigured-configuration
stars 3
issues 0
subscribers 0
forks 0
CREATED

UPDATED

nvim.pack

A minimalist, declarative Neovim configuration built on Neovim 0.12+'s native vim.pack package management, orchestrated by a custom loading engine (core.pack). No third-party plugin manager required.

Philosophy

  • Zero-latency startup: Only the colorscheme loads on the first frame (~18ms perceived interactive).
  • Declarative: All plugin loading logic is centralized in lua/plugins/init.lua.
  • On-demand: Plugins load only when needed (events, keymaps, or deferred).
  • No bloat: No lazy.nvim, packer.nvim, or paq-nvim — uses native :packadd.

Architecture

The configuration is built on three pillars:

  1. Entry Point (init.lua) — Sets core options, keymaps, autocmds, disables built-ins, and requires the plugin registry.
  2. Plugin Declarations (lua/plugins/init.lua) — Uses vim.pack.add({ ... }, { load = function() end }) to download plugins without adding them to the runtimepath or sourcing them automatically.
  3. Loading Engine (lua/core/pack.lua) — A declarative registry that dictates when and how plugins are loaded via :packadd and require.

Directory Structure

nvim.pack/
├── init.lua                 # Entry point
├── lua/
│   ├── core/
│   │   ├── autocmds.lua     # Global autocmds (highlight-yank, auto-save, session, build hooks, LSP log rotation)
│   │   ├── keymaps.lua      # Global keymaps
│   │   ├── native.lua       # Native replacements: lazygit, terminal, bufdelete, gitbrowse, scratch
│   │   ├── options.lua      # Global options
│   │   └── pack.lua         # The loading engine
│   └── plugins/
│       ├── init.lua         # Plugin declarations & loading registry
│       ├── catppuccin.lua   # Theme (loaded immediately)
│       ├── completion.lua   # blink.cmp
│       ├── debugging.lua    # DAP ecosystem
│       ├── deferred.lua     # render-markdown, colorizer, guess-indent, todo-comments
│       ├── editing.lua      # indent-blankline, rainbow-delimiters, conform
│       ├── git.lua          # gitsigns, diffview
│       ├── heirline.lua     # Statusline
│       ├── lsp.lua          # LSP, Mason, lazydev
│       ├── navigation.lua   # neo-tree, flash, spider
│       ├── telescope.lua    # Fuzzy finder
│       ├── tools.lua        # testing, database, diagnostics, productivity
│       ├── treesitter.lua   # TS core, context, textobjects
│       └── ui.lua           # which-key, native snacks replacements (terminal/lazygit/bufdelete/scratch), bigfile, quickfile
└── nvim-pack-lock.json      # Plugin version lock file

Loading Engine

The engine (lua/core/pack.lua) processes a registry array. Each entry defines a module and its loading trigger.

Registry Entry Schema

{
  mod     = 'domain_file', -- e.g., 'ui' (maps to lua/plugins/ui.lua)
  fn      = 'function',    -- (Optional) e.g., 'which_key' (calls M.which_key())
  packadd = { 'plugin' },  -- Array of plugin dir names to :packadd before loading
  -- Trigger (choose ONE):
  event   = 'UIEnter',     -- Autocmd event(s) (string or array)
  pattern = {'*.rs'},      -- (Optional) autocmd pattern; nil means all files
  keys    = { ... },       -- Array of { '<leader>x', desc = '...', mode = 'n' }
  defer   = 1,             -- Milliseconds to delay via vim.defer_fn
  -- If no trigger is provided, the module loads immediately (synchronously).
}

Loading Timeline

Phase Trigger What Loads
Immediate (none — synchronous) Catppuccin colorscheme only
VimEnter After init, before UI Native setup: bigfile guard, keymap wiring (lazygit/terminal/bufdelete/scratch)
UIEnter After first frame Heirline, which-key, navigation, editing (visual), ui-select
BufReadPre On file open Treesitter, LSP, rustaceanvim, gitsigns, treesitter-context
InsertEnter On first insert blink.cmp, autopairs
BufWritePre On save conform.nvim (formatting)
Keymap On first keypress Telescope, DAP, testing, database, diffview, trouble, productivity, surround, grug-far, treesj
Deferred After 1ms idle render-markdown, colorizer, guess-indent, todo-comments

CLI Tool

The nvim-pack binary provides two commands:

nvim-pack link

Link configuration resources to ~/.config/nvim/ as individual symlinks:

nvim-pack link           # Link all resources (init.lua, lua/, nvim-pack-lock.json)
nvim-pack link --dry-run # Preview changes without executing

nvim-pack bench

Benchmark Neovim startup time:

nvim-pack bench                        # Default: 30 iterations, 200ms settle
nvim-pack bench --iterations 50        # More iterations
nvim-pack bench --top 20               # Show top 20 slowest sources
nvim-pack bench --file /path/to/file   # Open a specific file

Thresholds: ≤50ms EXCELLENT, ≤80ms GOOD, ≤120ms FAIR, >120ms SLOW

Quick Start

1. Install the config

# Option A: Use nvim-pack CLI (recommended)
nvim-pack link

# Option B: Clone directly
git clone https://github.com/plutowang/nvim.pack.git ~/.config/nvim

2. First launch

On first launch, vim.pack will download all declared plugins. After that:

  • Treesitter parsers auto-install on first BufReadPre (deferred 500ms).
  • LSP servers auto-install via Mason on first BufReadPre.
  • blink.cmp's Rust fuzzy library compiles automatically via PackChanged on install/update (requires cargo).
  • Existing installations: Build the Rust library manually once:
    cd ~/.local/share/nvim/site/pack/core/opt/blink.cmp && cargo build --release

System Dependencies

Required

These tools must be installed for core functionality:

Tool Purpose Install
git Plugin downloads, version control macOS built-in or brew install git
curl Plugin downloads macOS built-in or brew install curl
rg Grep search (Telescope, grug-far) brew install ripgrep
fd File search (Telescope) brew install fd
tree-sitter Parser compilation cargo install tree-sitter-cli
make Build native extensions Xcode CLI tools (xcode-select --install)
cargo blink.cmp Rust fuzzy library brew install rust

Optional — Language Support

Mason auto-installs LSP servers, but some servers need language runtimes:

Language Required Tool Install LSP Servers Enabled
Go go brew install go gopls
TypeScript node / npm brew install node ts_ls, angularls, eslint
Python python3 macOS built-in pyright
Rust cargo brew install rust rust_analyzer
Zig zig brew install zig zls
HTML/CSS (none extra) — html, tailwindcss
GraphQL (none extra) — graphql
Astro node / npm brew install node astro
C/C++ clangd brew install llvm clangd

Adding or Modifying Plugins

To add a new plugin

  1. Declare it: Add the source to the vim.pack.add list in lua/plugins/init.lua.
  2. Configure it: Add a setup function to the appropriate domain file in lua/plugins/.
  3. Register it: Add an entry to the pack.setup registry in lua/plugins/init.lua, specifying mod, fn, packadd, and the loading trigger.

To modify an existing plugin

  1. Locate its domain file in lua/plugins/.
  2. Modify the specific exported function (e.g., M.format() in editing.lua).

To remove a plugin

  1. Remove the declaration: Delete the plugin from the vim.pack.add list in lua/plugins/init.lua.
  2. Remove the registry entry: Delete the corresponding entry from the pack.setup registry in lua/plugins/init.lua (the entry with mod = '...' that references the plugin in its packadd array).
  3. Remove from disk: Delete the plugin directory from ~/.local/share/nvim/site/pack/core/opt/<PluginName>.
  4. Clean the lock file (optional but recommended): Remove the plugin entry from nvim-pack-lock.json to keep it in sync. If vim.pack auto-repairs it back on next startup, the plugin directory still exists on disk — remove that first, then the lock entry will stay removed.

Known Pitfalls

  1. packadd Dependencies: If a plugin requires another plugin to function, you MUST include the dependency in the packadd array of the registry entry.
  2. vim.ui.select Overrides: Plugins that override core Neovim functions (like telescope-ui-select) MUST be loaded early (on UIEnter), even if the main plugin is loaded lazily via keymaps.
  3. Headless Mode: The core.pack engine does NOT bypass lazy loading in headless mode. Trigger the specific event or keymap to load a plugin during a headless script.
  4. Augroup Collisions: The engine creates augroups named 'pack-' .. entry.mod .. '-' .. entry.fn. Never manually create augroups with this naming scheme.
  5. Keymap Replay: The engine's keymap trigger uses nvim_feedkeys to replay the initial keypress. Ensure the plugin's actual keymap exactly matches the trigger keymap.

Troubleshooting

blink.cmp "No fuzzy matching Library found"

This error appears when the Rust fuzzy library hasn't been compiled. blink.cmp's error message references lazy.nvim (its most common plugin manager), but the fix is the same regardless of plugin manager:

cd ~/.local/share/nvim/site/pack/core/opt/blink.cmp && cargo build --release

The PackChanged autocmd runs this automatically on install/update. If you don't have cargo installed, the config falls back to the Lua fuzzy implementation via fuzzy.implementation = 'prefer_rust' in lua/plugins/completion.lua. To force Lua-only matching, change it to 'lua'.