kickstart.nvim/MIGRATION.md

Migration Checklist - Neovim Config Refactor

Current State ✅

• Working Python LSP (pyright)
• Working Flutter LSP (dartls)
• Lazy-loaded language profiles
• Common plugins loaded globally
• ~1200 line init.lua (needs refactoring)

Phase 1: Understand Your Config (Before Refactoring)

• Read through entire init.lua - understand every line
• List all plugins you actually use (vs installed)
• Identify startup bottlenecks: nvim --startuptime startup.log
• Document your most-used keybindings
• Run :checkhealth to verify everything works

Phase 2: Extract Configuration (Low Risk)

• Create lua/config/options.lua - Move all vim.opt settings
• Create lua/config/keymaps.lua - Move global keymaps
• Create lua/config/autocmds.lua - Move global autocmds
• Update init.lua to require these modules
• Test: Restart nvim, verify everything works

Phase 3: Reorganize Plugins (Medium Risk)

• Create lua/plugins/core/ directory structure
• Move UI plugins to core/ui.lua
• Move editor plugins to core/editor.lua
• Move git plugins to core/git.lua
• Move completion to core/completion.lua
• Test after EACH move - don't batch them!

Phase 4: Refactor LSP (High Risk - Do Last!)

• Create lua/plugins/lsp/init.lua for mason setup
• Create lua/plugins/lsp/servers.lua for general servers (lua_ls)
• Move language-specific LSP to their lang files
• Create lua/util/lsp.lua for shared utilities
• Test each language: Python, Flutter, Svelte

Phase 5: Cleanup

• Remove unused plugins (check with :Lazy)
• Remove duplicate code
• Add comments explaining WHY, not WHAT
• Update README.md with your structure
• Profile startup time - compare before/after

Testing Checklist (Run After Each Phase)

• Python: Open .py file, verify pyright loads, test completion
• Flutter: Open .dart file, verify dartls loads, test completion
• Svelte: Open .svelte file, verify svelte-ls loads
• Git: Open a git repo, test gitsigns
• Telescope: Test fuzzy finding (sf)
• LSP: Test go-to-definition, hover, rename
• Formatting: Test format-on-save
• Sessions: Test session save/restore

Rollback Plan

# Before starting, create a backup branch
cd ~/.config/nvim
git checkout -b refactor-backup
git checkout -b refactor-attempt

# If something breaks:
git checkout refactor-backup

Performance Targets

Metric	Before	Target	After
Startup time	? ms	<100ms	? ms
Plugins loaded on startup	?	<30	?
Time to first edit	? ms	<200ms	? ms

Measure with:

nvim --startuptime startup.log
# Check the last line for total time

When NOT to Refactor

• You don't understand why your current config works
• You're in the middle of a project deadline
• Your startup time is already <50ms
• You haven't backed up your config

When TO Refactor

• Your init.lua is >500 lines (yours is 1200!)
• You have duplicate code across files
• You're adding a 4th+ language (you have 3)
• Startup time is >200ms
• You want to understand how Neovim works

Expected Benefits

• Faster startup (lazy-loading)
• Easier to add new languages (template)
• Easier to debug (modular)
• Easier to share/document
• Better understanding of Neovim

Expected Challenges

• LSP loading timing issues (we already solved this!)
• Plugin dependency conflicts
• Breaking changes in lazy.nvim API
• Time investment (plan 4-6 hours)

---

Quick Win: Do This First (30 minutes)

1. Extract options (lowest risk, immediate clarity):

-- lua/config/options.lua
vim.g.mapleader = ' '
vim.g.maplocalleader = ' '
vim.g.have_nerd_font = true
vim.opt.number = true
vim.opt.relativenumber = true
-- ... all your vim.opt settings

2. Extract keymaps:

-- lua/config/keymaps.lua
-- Escape closes floating windows
vim.keymap.set('n', '<Esc>', function()
  -- ... your escape logic
end)

3. Update init.lua:

-- NEW init.lua (first 3 lines!)
require('config.options')
require('config.keymaps')
-- ... rest stays the same for now

This alone will make your init.lua 200 lines shorter and much clearer!

---

Resources to Keep Handy

• Lazy.nvim Spec
• :help lua-guide
• Your ORGANIZATION.md
• Kickstart.nvim (reference only)

---

Remember: Refactoring is optional. Your current setup WORKS. Only refactor if:

1. You want to learn more about Neovim
2. You want to add many more languages
3. Your startup time bothers you
4. You enjoy organizing code

Good luck! 🚀