Configuring Neovim with `init.lua`: A Comprehensive Guide

-- Basic settings vim.o.number = true -- Enable line numbers vim.o.relativenumber = true -- Enable relative line numbers vim.o.tabstop = 4 -- Number of spaces a tab represents vim.o.shiftwidth = 4 -- Number of spaces for each indentation vim.o.expandtab = true -- Convert tabs to spaces vim.o.smartindent = true -- Automatically indent new lines vim.o.wrap = false -- Disable line wrapping vim.o.cursorline = true -- Highlight the current line vim.o.termguicolors = true -- Enable 24-bit RGB colors -- Syntax highlighting and filetype plugins vim.cmd('syntax enable') vim.cmd('filetype plugin indent on') -- Leader key vim.g.mapleader = ' ' -- Space as the leader key vim.api.nvim_set_keymap('n', '<Leader>w', ':w<CR>', { noremap = true, silent = true }) 

~/.config/nvim/ ├── init.lua # Main entry point ├── lua/ │ ├── user/ │ │ ├── options.lua # Editor options │ │ ├── keymaps.lua # Key mappings │ │ ├── plugins.lua # Plugin management │ │ ├── lsp.lua # LSP configurations │ │ └── ... 

-- Initialize core settings first require('user.options') require('user.keymaps') -- Load plugin manager require('user.plugins') -- Set up plugins with dependencies require('user.treesitter') -- Set up before LSP for better highlighting require('user.lsp') -- Depends on language servers being available require('user.completion') -- Depends on LSP configuration require('user.telescope') -- Often integrates with LSP -- Configure UI components last require('user.theme') require('user.statusline') 

options/keymaps (independent) -> plugins manager -> treesitter -> LSP (requires language servers) -> completion (requires LSP) -> UI components 

-- plugins.lua -- Bootstrap Lazy.nvim if not installed local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" if not vim.loop.fs_stat(lazypath) then print("Installing lazy.nvim...") vim.fn.system({ "git", "clone", "--filter=blob:none", "https://github.com/folke/lazy.nvim.git", "--branch=stable", -- latest stable release lazypath, }) print("Lazy.nvim installed!") end vim.opt.rtp:prepend(lazypath) -- Plugin specifications return require("lazy").setup({ -- Essential plugins "nvim-lua/plenary.nvim", -- Utility functions (dependency for many plugins) -- Treesitter for syntax highlighting (load early) { "nvim-treesitter/nvim-treesitter", build = ":TSUpdate", priority = 100, -- Load early }, -- Language Server Protocol support { "neovim/nvim-lspconfig", -- Base LSP configurations dependencies = { -- Server installation manager "williamboman/mason.nvim", "williamboman/mason-lspconfig.nvim", }, }, -- Autocompletion system { "hrsh7th/nvim-cmp", dependencies = { "hrsh7th/cmp-nvim-lsp", -- LSP source for nvim-cmp "hrsh7th/cmp-buffer", -- Buffer source "hrsh7th/cmp-path", -- Path source "L3MON4D3/LuaSnip", -- Snippet engine "saadparwaiz1/cmp_luasnip", -- Snippet source }, }, -- File explorer { "nvim-tree/nvim-tree.lua", dependencies = { "nvim-tree/nvim-web-devicons" }, }, -- Fuzzy finder { "nvim-telescope/telescope.nvim", dependencies = { "nvim-lua/plenary.nvim" } }, -- Key binding helper { "folke/which-key.nvim", }, -- Theme (load last after all functionality is configured) { "catppuccin/nvim", name = "catppuccin", priority = 1000, -- Load last }, }) 

-- plugins.lua -- Bootstrap Packer if not installed local install_path = vim.fn.stdpath('data')..'/site/pack/packer/start/packer.nvim' if vim.fn.empty(vim.fn.glob(install_path)) > 0 then print("Installing packer...") vim.fn.system({'git', 'clone', '--depth', '1', 'https://github.com/wbthomason/packer.nvim', install_path}) vim.cmd 'packadd packer.nvim' print("Packer installed!") end -- Initialize and configure plugins return require('packer').startup(function(use) use 'wbthomason/packer.nvim' -- Packer manages itself use 'nvim-lua/plenary.nvim' -- Utility functions -- Essential plugins with clear dependency structure -- Load order: -- 1. Treesitter (syntax) -- 2. LSP (intelligence) -- 3. Completion (depends on LSP) -- 4. UI and utilities -- 1. Treesitter first use { 'nvim-treesitter/nvim-treesitter', run = ':TSUpdate', } -- 2. LSP setup with server management use { 'neovim/nvim-lspconfig', requires = { 'williamboman/mason.nvim', -- Server installer 'williamboman/mason-lspconfig.nvim', } } -- 3. Autocompletion (depends on LSP) use { 'hrsh7th/nvim-cmp', requires = { 'hrsh7th/cmp-nvim-lsp', -- LSP source 'hrsh7th/cmp-buffer', 'hrsh7th/cmp-path', 'L3MON4D3/LuaSnip', 'saadparwaiz1/cmp_luasnip', } } -- 4. UI and utilities use { 'nvim-tree/nvim-tree.lua', requires = 'nvim-tree/nvim-web-devicons' } use { 'nvim-telescope/telescope.nvim', requires = 'nvim-lua/plenary.nvim' } use 'folke/which-key.nvim' -- Theme (load last) use { 'catppuccin/nvim', as = 'catppuccin' } end) 

-- treesitter.lua require('nvim-treesitter.configs').setup { -- Install these parsers by default ensure_installed = { "lua", "vim", "vimdoc", "javascript", "typescript", "python", "rust", "go", "html", "css", "json", "yaml", "toml", "markdown", "bash" }, auto_install = true, -- Automatically install missing parsers highlight = { enable = true, additional_vim_regex_highlighting = false, }, indent = { enable = true }, incremental_selection = { enable = true, keymaps = { init_selection = "<CR>", node_incremental = "<CR>", node_decremental = "<BS>", }, }, } 

-- lsp.lua -- Install Mason first for managing servers require("mason").setup({ ui = { icons = { package_installed = "✓", package_pending = "➜", package_uninstalled = "✗" } } }) -- Connect Mason with lspconfig require("mason-lspconfig").setup({ -- Automatically install these servers ensure_installed = { "lua_ls", -- Lua "pyright", -- Python "tsserver", -- TypeScript/JavaScript "rust_analyzer", -- Rust "gopls", -- Go "clangd", -- C/C++ }, automatic_installation = true, }) -- Set up LSP capabilities (used by completion) local capabilities = vim.lsp.protocol.make_client_capabilities() -- Check if nvim-cmp is available to enhance capabilities local has_cmp, cmp_lsp = pcall(require, 'cmp_nvim_lsp') if has_cmp then capabilities = cmp_lsp.default_capabilities(capabilities) end -- Function to set up all installed LSP servers local on_attach = function(client, bufnr) -- Enable completion triggered by <c-x><c-o> vim.api.nvim_buf_set_option(bufnr, 'omnifunc', 'v:lua.vim.lsp.omnifunc') -- Key mappings local bufopts = { noremap=true, silent=true, buffer=bufnr } vim.keymap.set('n', 'gD', vim.lsp.buf.declaration, bufopts) vim.keymap.set('n', 'gd', vim.lsp.buf.definition, bufopts) vim.keymap.set('n', 'K', vim.lsp.buf.hover, bufopts) vim.keymap.set('n', 'gi', vim.lsp.buf.implementation, bufopts) vim.keymap.set('n', '<C-k>', vim.lsp.buf.signature_help, bufopts) vim.keymap.set('n', '<leader>rn', vim.lsp.buf.rename, bufopts) vim.keymap.set('n', '<leader>ca', vim.lsp.buf.code_action, bufopts) vim.keymap.set('n', 'gr', vim.lsp.buf.references, bufopts) vim.keymap.set('n', '<leader>lf', function() vim.lsp.buf.format { async = true } end, bufopts) -- Log a message when a server attaches print(string.format("LSP server '%s' attached to this buffer", client.name)) end -- Set up all servers installed via Mason require("mason-lspconfig").setup_handlers { -- Default handler for installed servers function(server_name) require('lspconfig')[server_name].setup { on_attach = on_attach, capabilities = capabilities, } end, -- Special configurations for specific servers ["lua_ls"] = function() require('lspconfig').lua_ls.setup { on_attach = on_attach, capabilities = capabilities, settings = { Lua = { runtime = { version = 'LuaJIT' }, diagnostics = { globals = {'vim'} }, workspace = { library = vim.api.nvim_get_runtime_file("", true), checkThirdParty = false, }, telemetry = { enable = false }, }, }, } end, } -- Configure diagnostic display vim.diagnostic.config({ virtual_text = { prefix = '●', -- Could be '■', '▎', 'x' source = "if_many", }, float = { source = "always", border = "rounded", }, signs = true, underline = true, update_in_insert = false, severity_sort = true, }) -- Change diagnostic symbols in the sign column local signs = { Error = " ", Warn = " ", Hint = " ", Info = " " } for type, icon in pairs(signs) do local hl = "DiagnosticSign" .. type vim.fn.sign_define(hl, { text = icon, texthl = hl, numhl = hl }) end 

-- completion.lua local has_cmp, cmp = pcall(require, 'cmp') if not has_cmp then print("Warning: nvim-cmp not found. Autocompletion won't be available.") return end local has_luasnip, luasnip = pcall(require, 'luasnip') if not has_luasnip then print("Warning: luasnip not found. Snippet expansion won't be available.") return end cmp.setup({ snippet = { expand = function(args) luasnip.lsp_expand(args.body) end, }, window = { completion = cmp.config.window.bordered(), documentation = cmp.config.window.bordered(), }, mapping = cmp.mapping.preset.insert({ ['<C-b>'] = cmp.mapping.scroll_docs(-4), ['<C-f>'] = cmp.mapping.scroll_docs(4), ['<C-Space>'] = cmp.mapping.complete(), ['<C-e>'] = cmp.mapping.abort(), ['<CR>'] = cmp.mapping.confirm({ select = false }), -- Accept explicitly selected item -- Tab support ['<Tab>'] = cmp.mapping(function(fallback) if cmp.visible() then cmp.select_next_item() elseif luasnip.expand_or_jumpable() then luasnip.expand_or_jump() else fallback() end end, { 'i', 's' }), ['<S-Tab>'] = cmp.mapping(function(fallback) if cmp.visible() then cmp.select_prev_item() elseif luasnip.jumpable(-1) then luasnip.jump(-1) else fallback() end end, { 'i', 's' }), }), sources = cmp.config.sources({ { name = 'nvim_lsp' }, { name = 'luasnip' }, { name = 'buffer' }, { name = 'path' }, }), formatting = { format = function(entry, vim_item) -- Add icons vim_item.menu = ({ nvim_lsp = "[LSP]", luasnip = "[Snippet]", buffer = "[Buffer]", path = "[Path]", })[entry.source.name] return vim_item end, }, }) -- Enable command-line completion cmp.setup.cmdline(':', { mapping = cmp.mapping.preset.cmdline(), sources = cmp.config.sources({ { name = 'path' }, { name = 'cmdline' } }) }) print("Completion system initialized!") 

-- explorer.lua -- Check if nvim-tree is available local has_tree, nvim_tree = pcall(require, "nvim-tree") if not has_tree then print("Warning: nvim-tree not found. File explorer won't be available.") return end -- Set up nvim-tree with error handling local setup_ok, _ = pcall(nvim_tree.setup, { sort_by = "case_sensitive", view = { width = 30, }, renderer = { group_empty = true, icons = { show = { git = true, folder = true, file = true, folder_arrow = true, }, }, }, filters = { dotfiles = false, }, git = { enable = true, ignore = false, }, actions = { open_file = { quit_on_open = false, resize_window = true, }, }, }) if not setup_ok then print("Error setting up nvim-tree. Some features might not work correctly.") return end -- Recommended mappings vim.keymap.set('n', '<leader>e', '<cmd>NvimTreeToggle<CR>', { desc = "Toggle file explorer" }) vim.keymap.set('n', '<leader>fe', '<cmd>NvimTreeFocus<CR>', { desc = "Focus file explorer" }) print("File explorer initialized!") 

-- telescope.lua -- Check if telescope is available local has_telescope, telescope = pcall(require, "telescope") if not has_telescope then print("Warning: telescope not found. Fuzzy finding won't be available.") return end -- Set up telescope with error handling local setup_ok, _ = pcall(telescope.setup, { defaults = { prompt_prefix = "🔍 ", selection_caret = "❯ ", path_display = { "truncate" }, layout_config = { horizontal = { preview_width = 0.55, results_width = 0.8, }, width = 0.87, height = 0.80, preview_cutoff = 120, }, file_ignore_patterns = { "node_modules/", ".git/", ".DS_Store" }, }, extensions = { -- Configure any extensions here } }) if not setup_ok then print("Error setting up telescope. Some features might not work correctly.") return end -- Load telescope extensions if available pcall(function() require('telescope').load_extension('fzf') end) -- Useful Telescope mappings with error handling local builtin_ok, builtin = pcall(require, 'telescope.builtin') if builtin_ok then vim.keymap.set('n', '<leader>ff', builtin.find_files, { desc = "Find files" }) vim.keymap.set('n', '<leader>fg', builtin.live_grep, { desc = "Live grep" }) vim.keymap.set('n', '<leader>fb', builtin.buffers, { desc = "Buffers" }) vim.keymap.set('n', '<leader>fh', builtin.help_tags, { desc = "Help tags" }) -- LSP-related searches vim.keymap.set('n', '<leader>fd', builtin.lsp_definitions, { desc = "Find definitions" }) vim.keymap.set('n', '<leader>fr', builtin.lsp_references, { desc = "Find references" }) end print("Fuzzy finder initialized!") 

-- whichkey.lua -- Check if which-key is available local has_which_key, which_key = pcall(require, "which-key") if not has_which_key then print("Warning: which-key not found. Key binding help won't be available.") return end -- Set up which-key with error handling local setup_ok, _ = pcall(which_key.setup, { plugins = { marks = true, registers = true, spelling = { enabled = true, suggestions = 20, }, presets = { operators = true, motions = true, text_objects = true, windows = true, nav = true, z = true, g = true, }, }, window = { border = "rounded", padding = { 2, 2, 2, 2 }, }, layout = { height = { min = 4, max = 25 }, width = { min = 20, max = 50 }, }, ignore_missing = false, }) if not setup_ok then print("Error setting up which-key. Key binding help won't work correctly.") return end -- Register key bindings with which-key local register_ok, _ = pcall(which_key.register, { f = { name = "File", -- Optional group name f = { "<cmd>Telescope find_files<cr>", "Find File" }, r = { "<cmd>Telescope oldfiles<cr>", "Recent Files" }, g = { "<cmd>Telescope live_grep<cr>", "Live Grep" }, b = { "<cmd>Telescope buffers<cr>", "Buffers" }, n = { "<cmd>enew<cr>", "New File" }, }, e = { "<cmd>NvimTreeToggle<cr>", "Explorer" }, l = { name = "LSP", d = { "<cmd>Telescope lsp_definitions<cr>", "Definitions" }, r = { "<cmd>Telescope lsp_references<cr>", "References" }, a = { "<cmd>lua vim.lsp.buf.code_action()<cr>", "Code Action" }, f = { "<cmd>lua vim.lsp.buf.format()<cr>", "Format" }, h = { "<cmd>lua vim.lsp.buf.hover()<cr>", "Hover" }, R = { "<cmd>lua vim.lsp.buf.rename()<cr>", "Rename" }, }, b = { name = "Buffer", n = { "<cmd>bnext<cr>", "Next Buffer" }, p = { "<cmd>bprevious<cr>", "Previous Buffer" }, d = { "<cmd>bdelete<cr>", "Delete Buffer" }, }, }, { prefix = "<leader>" }) if not register_ok then print("Error registering which-key bindings.") return end print("Key binding help initialized!") 

-- theme.lua -- Set the colorscheme with error handling local colorscheme_ok, _ = pcall(vim.cmd, [[colorscheme catppuccin]]) if not colorscheme_ok then print("Warning: catppuccin theme not found. Falling back to default theme.") return end -- Configure Catppuccin theme (only if available) local has_catppuccin, catppuccin = pcall(require, "catppuccin") if has_catppuccin then local setup_ok, _ = pcall(catppuccin.setup, { flavour = "mocha", -- latte, frappe, macchiato, mocha transparent_background = false, term_colors = true, integrations = { cmp = true, nvimtree = true, telescope = true, treesitter = true, which_key = true, }, }) if not setup_ok then print("Error setting up catppuccin theme. Using default configuration.") end end print("Theme initialized!") 

-- Add to your init.lua for better compatibility with existing Vim setup -- Respect XDG base directories standard local vim_config_path = vim.fn.expand('~/.vimrc') local vim_config_exists = vim.fn.filereadable(vim_config_path) == 1 -- Load existing Vim configuration if desired if vim_config_exists and vim.g.load_vimrc ~= false then vim.cmd('source ' .. vim_config_path) print("Loaded existing .vimrc for compatibility") end -- Set compatibility options vim.opt.compatible = false vim.opt.backspace = {"indent", "eol", "start"} 

-- Basic error handling wrapper for module loading local function safe_require(module) local success, result = pcall(require, module) if not success then vim.notify("Error loading module '" .. module .. "': " .. result, vim.log.levels.ERROR) return nil end return result end -- Then use it for loading modules local treesitter = safe_require("user.treesitter") 

-- Add to your init.lua or run in command mode vim.cmd([[ augroup TreesitterInstall autocmd! autocmd VimEnter * TSInstall lua vim vimdoc javascript typescript python rust go html css json yaml toml markdown bash augroup END ]]) 

:TSInstall lua python javascript typescript 

-- Check if you have the necessary system dependencies -- For example, for Python's pyright, you need npm/node.js -- For rust-analyzer, you need rustup -- Manual installation fallback for a server -- Example for pyright vim.cmd([[ !npm install -g pyright ]]) 

:Lazy clear -- Clear plugin cache :Lazy sync -- Try reinstalling plugins 

:PackerClean :PackerSync 

-- Add to end of your lsp.lua -- Print info about active language servers vim.api.nvim_create_user_command('LspInfo', function() local clients = vim.lsp.get_active_clients() if #clients == 0 then print("No active LSP clients.") return end for _, client in ipairs(clients) do print(string.format( "LSP client: %s (id: %d) - root: %s", client.name, client.id, client.config.root_dir or "not set" )) end end, {})