Geoffrey Kim

Posted on Feb 21, 2024 • Edited on Mar 18

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

#neovim #lua #programming #editor

Neovim is a highly configurable text editor built for power users who want to enhance their development workflow. With the introduction of the Lua configuration file (init.lua), Neovim users can achieve an even higher degree of customization and efficiency. This guide will walk you through configuring Neovim using init.lua, addressing common issues, and providing rich examples to help you create an optimal setup.

Compatibility and Prerequisites

Important: This guide is designed for Neovim v0.7.0 and above. Some features may not work on older versions.

Before diving into configuration:

Ensure you have Neovim v0.7.0+ installed (nvim --version)
Basic knowledge of Lua is helpful but not required
If you're migrating from Vim, see the Vim-to-Neovim migration section

Setting Up Your `init.lua`

The init.lua file is the cornerstone of your Neovim configuration, allowing you to specify settings, key mappings, and plugins. Here's how to get started with a basic init.lua:

-- 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 })

Organizing Your Configuration

Instead of keeping all your settings in a single init.lua file, you can organize your configuration into modules for better maintainability. Here's a recommended structure:

~/.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
│   │   └── ...

Your main init.lua would then load these modules in the correct order (important for dependencies):

-- 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')

Component Dependencies Overview

Here's a dependency graph of the major components to understand loading order:

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

Plugin Management Setup

Using Lazy.nvim (Recommended for Neovim 0.7+)

Lazy.nvim is a modern plugin manager with improved performance, lazy-loading capabilities, and a simple API. Here's how to set it up:

-- 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
  },
})

Using Packer (Alternative for Neovim 0.5+)

-- 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)

Core Component Setup (Step-by-Step)

1. Treesitter for Enhanced Syntax

First, configure Treesitter for better syntax highlighting:

-- 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>",
    },
  },
}

2. Language Server Protocol (LSP) with Mason

Next, set up the LSP with Mason for automatic server installation:

-- 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

3. Autocompletion with nvim-cmp

Now set up autocompletion with LSP integration:

-- 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!")

4. File Explorer with NvimTree

Set up a modern file explorer:

-- 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!")

5. Fuzzy Finder with Telescope

Configure a powerful fuzzy finder:

-- 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!")

6. Key Binding Display with Which-Key

Organize and document your key bindings:

-- 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!")

7. Theme Configuration

Apply a modern theme with error handling:

-- 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!")

Migrating from Vim

If you're migrating from Vim to Neovim, here are some tips to make the transition smoother:

-- 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"}

Troubleshooting Common Issues

Error Detection and Handling

Add this to your init.lua for better error detection:

-- 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")

Treesitter Parser Installation Issues

If Treesitter parsers fail to install automatically:

-- 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
]])

Alternatively, manually install parsers:

:TSInstall lua python javascript typescript

LSP Server Installation Issues

If you encounter issues with Mason installing servers:

-- 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
]])

Plugin Installation Failures

If plugins fail to install with Lazy.nvim:

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

With Packer:

:PackerClean
:PackerSync

Language Server Configuration Not Working

Diagnostic steps to try:

-- 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, {})

Use :LspInfo to debug active language servers.

Verification and Testing Your Setup

After configuring your Neovim setup, verify that everything is working:

Plugin Installation: Run :Lazy sync or :PackerSync to ensure all plugins are installed
LSP Status: Use :LspInfo to check if language servers are running
Treesitter: Use :TSInstallInfo to check installed parsers
Syntax Highlighting: Open files in different languages to verify syntax highlighting
Completion: Type code to check if autocompletion is working
Keybindings: Press <leader> and wait to see if which-key appears

Conclusion

Configuring Neovim with init.lua unlocks a powerful and personalized development environment. By following a modular, dependency-aware approach with proper error handling, you can create a robust, efficient editor tailored to your workflow.

The Neovim ecosystem is constantly evolving, so stay updated by following:

The Neovim GitHub repository
The Neovim subreddit
Plugin GitHub repositories for updates

Remember that your configuration should grow organically with your needs. Start with the essentials, ensure they work properly, and gradually add more features as you become comfortable with your setup.

Top comments (1)

david diem • Jun 8 '24

Thanks for the guidance