vim

name	vim
description	[Applies to: **/*] Definitive guidelines for configuring and using Vim/Neovim as a high-performance, terminal-centric IDE, emphasizing modern practices, efficient plugin management, and advanced workflows.
source	cursor_mdc

vim Best Practices

Vim (and especially Neovim) is a powerful, programmable editor. Treat it as a foundation for a custom IDE. This guide focuses on modern Neovim practices, which are largely applicable to Vim 8+ with appropriate plugin choices.

1. Configuration Organization & Structure

Always use a structured configuration. For Neovim, this means Lua files in ~/.config/nvim/. For Vim, use ~/.vimrc. Lua offers superior expressiveness and performance.

✅ GOOD: Neovim with Lua (recommended) Organize your init.lua by sourcing smaller, focused files.

-- ~/.config/nvim/init.lua
require('options')    -- Core editor settings
require('keymaps')     -- Custom keybindings
require('plugins')    -- Plugin manager setup and lazy loading
require('autocmds')   -- Automatic commands

❌ BAD: Monolithic init.vim / init.lua A single, unorganized file becomes unmanageable and hard to debug.

" ~/.vimrc (or init.lua) - Avoid this sprawl
set number
map <leader>s :w<CR>
" ... hundreds of lines ...

2. Essential Configuration Patterns

2.1. Sensible Defaults

Disable compatible mode immediately. Set fundamental options for a modern editing experience.

✅ GOOD: Modern Defaults

-- In lua/options.lua
vim.opt.termguicolors = true   -- Enable true colors in terminal
vim.opt.number = true          -- Show line numbers
vim.opt.relativenumber = true  -- Show relative line numbers
vim.opt.expandtab = true       -- Use spaces instead of tabs
vim.opt.shiftwidth = 4         -- Number of spaces for indent
vim.opt.tabstop = 4            -- Number of spaces a tab counts for
vim.opt.autoindent = true      -- Copy indent from previous line
vim.opt.smartindent = true     -- Smart auto-indent for C-like files
vim.opt.undofile = true        -- Persistent undo history
vim.opt.backup = false         -- No backup files (use Git!)
vim.opt.writebackup = false    -- No backup files during write
vim.opt.swapfile = false       -- No swap files
vim.opt.hlsearch = true        -- Highlight search results
vim.opt.incsearch = true       -- Incremental search
vim.opt.scrolloff = 8          -- Keep 8 lines of context
vim.opt.updatetime = 300       -- Faster UI updates for plugins
vim.opt.timeoutlen = 500       -- Shorter key sequence timeout
vim.opt.cmdheight = 1          -- Command line height
vim.opt.laststatus = 2         -- Always show status line
vim.opt.showmode = false       -- Don't show -- INSERT -- etc.
vim.opt.signcolumn =      
vim.opt.cursorline =       
vim.opt. =            
vim.opt.mouse =             
vim.opt.clipboard =  

❌ BAD: Vi-compatible or minimal defaults Sticking to Vi's ancient defaults hinders productivity.

" ~/.vimrc
set compatible " NEVER do this!
set nobackup   " This is fine, but missing many other essentials

2.2. Key Mappings

Use <leader> for all custom mappings to avoid conflicts and provide a consistent prefix.

✅ GOOD: Leader-prefixed Mappings

-- In lua/keymaps.lua
vim.g.mapleader = ' ' -- Set space as the leader key

-- Save file
vim.keymap.set('n', '<leader>w', '<cmd>w<CR>', { desc = 'Save File' })
-- Toggle NvimTree
vim.keymap.set('n', '<leader>e', '<cmd>NvimTreeToggle<CR>', { desc = 'Toggle File Explorer' })

❌ BAD: Overwriting built-in commands Directly mapping common keys like s or q leads to frustration.

" ~/.vimrc
map s :w<CR> " This overwrites the 'substitute' command!

2.3. Asynchronous Plugin Management

Always use a lazy-loading plugin manager. lazy.nvim is the current standard for Neovim. It drastically improves startup time by loading plugins only when needed.

✅ GOOD: Lazy Loading with lazy.nvim

-- In lua/plugins.lua
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({
  -- LSP Configuration
  {
    'neovim/nvim-lspconfig',
    dependencies = {
      'williamboman/mason.nvim',
      'williamboman/mason-lspconfig.nvim',
    },
    config = function()
      require('lsp_config') -- Separate LSP setup
    end
  },
  -- Fuzzy Finder
  {
    'nvim-telescope/telescope.nvim',
    tag = '0.1.x',
    dependencies = { 'nvim-lua/plenary.nvim' },
    keys = {
      { '<leader>ff', '<cmd>Telescope find_files<CR>', desc = 'Find Files' },
      { '<leader>fg', '<cmd>Telescope live_grep<CR>', desc = 'Live Grep' },
    },
  },
  -- Tree-sitter for syntax highlighting
  {
    'nvim-treesitter/nvim-treesitter',
    build = ':TSUpdate',
    config = function()
      require('nvim-treesitter.configs').setup {
        ensure_installed = { , , , , , ,  },
        highlight = { enable =  },
        indent = { enable =  },
      }
    ,
  },
  
  {
    ,
     =  ().setup() ,
  },
  
  {
    ,
    lazy = , 
    cmd = { ,  },
     =  ().setup() ,
  },
})

❌ BAD: Synchronous plugin loading Loading all plugins at startup, especially heavy ones, makes Vim slow.

" ~/.vimrc
packadd nvim-lspconfig " Loads immediately, even if not needed

3. Performance Considerations

Prioritize asynchronous operations and minimize UI redraws.

✅ GOOD: Asynchronous Linting & Formatting Use Neovim's built-in LSP diagnostics for real-time feedback. Format on save via autocmd.

-- In lua/lsp_config.lua (example for formatting)
vim.api.nvim_create_autocmd('BufWritePre', {
  pattern = '*',
  callback = function(args)
    vim.lsp.buf.format({ async = true, bufnr = args.buf })
  end,
})

❌ BAD: Blocking external commands Running !fmt % blocks the editor until the command finishes.

" ~/.vimrc
autocmd BufWritePre *.go !goimports -w % " Blocks Vim

4. Common Pitfalls & Gotchas

4.1. Forgetting set nocompatible

This is the most common mistake for new Vim users. Always disable compatible mode.

❌ BAD:

" ~/.vimrc
" (no set nocompatible) -> Vim behaves like ancient Vi

✅ GOOD:

-- In lua/options.lua
vim.opt.compatible = false

4.2. Ignoring LSP

Modern IDE features (go-to-definition, refactoring, autocompletion) are powered by Language Servers. Integrate nvim-lspconfig with mason.nvim.

❌ BAD: Relying solely on regex-based tools grep and ctags are useful but lack semantic understanding.

" ~/.vimrc
map <leader>gd :grep -R <cword> .<CR> " Not semantic

✅ GOOD: Full LSP Integration

-- In lua/lsp_config.lua
local lspconfig = require('lspconfig')
local mason_lspconfig = require('mason-lspconfig')
local capabilities = vim.lsp.protocol.make_client_capabilities()
-- ... add completion capabilities etc.

mason_lspconfig.setup_handlers {
  function(server_name)
    lspconfig[server_name].setup {
      capabilities = capabilities,
      -- ... other server-specific settings
    }
  end,
}

5. Testing & Debugging Approaches

Leverage Neovim's built-in terminal and quickfix list for efficient testing and error navigation.

✅ GOOD: Integrated Terminal for Tests Run tests in a split window and navigate output.

-- In lua/keymaps.lua
vim.keymap.set('n', '<leader>tt', '<cmd>split term://go test ./...<CR>', { desc = 'Run Go Tests' })
vim.keymap.set('n', '<leader>tc', '<cmd>split term://npm test<CR>', { desc = 'Run NPM Tests' })

❌ BAD: Switching to external terminal Context switching breaks flow and is inefficient.

" ~/.vimrc
map <leader>t :!go test ./...<CR> " Blocks Vim, output not easily navigable

✅ GOOD: Quickfix List for Errors Populate the quickfix list with linter/compiler errors and use :cprev / :cnext to navigate.

-- LSP diagnostics automatically populate the quickfix/location list.
-- Ensure you have mappings for navigation:
vim.keymap.set('n', '[d', vim.diagnostic.goto_prev, { desc = 'Go to previous diagnostic' })
vim.keymap.set('n', ']d', vim.diagnostic.goto_next, { desc = 'Go to next diagnostic' })
vim.keymap.set('n', '<leader>qf', '<cmd>copen<CR>', { desc = 'Open Quickfix List' })