lazydev.nvim

lazydev.nvim optimizes LuaLS by lazily updating workspace libraries based on your code. It automatically detects and loads modules for:

• require statements: e.g., require("nvim-treesitter")
• module annotations: e.g., ---@module "nvim-treesitter"

This approach ensures faster autocompletion because only the modules actually used in your open files are loaded into the LuaLS workspace.

Limitations to note:

• If a file only uses types from a plugin without require-ing it or using a module annotation, those types won't be available. To fix this, pre-load the plugin using the library option.
• Completion for module names in require(...) only returns modules currently loaded in your workspace. To see all available modules, use the nvim-cmp, blink.cmp, or coq_nvim completion sources provided by lazydev.
• Neovim >= 0.10: Neovim types are no longer included or required.

To install lazydev.nvim, use the following configuration with lazy.nvim. It is recommended to set ft = "lua" so the plugin only loads for Lua files.

Additionally, you can install optional completion sources for nvim-cmp or blink.cmp to improve autocompletion for require statements and module annotations.

Note: If you previously used neodev.nvim, ensure it is uninstalled or disabled to avoid conflicts.

return {
  {
    "folke/lazydev.nvim",
    ft = "lua", -- only load on lua files
    opts = {
      library = {
        -- See the configuration section for more details
        -- Load luvit types when the `vim.uv` word is found
        { path = "${3rd}/luv/library", words = { "vim%.uv" } },
      },
    },
  },
  { -- optional cmp completion source for require statements and module annotations
    "hrsh7th/nvim-cmp",
    opts = function(_, opts)
      opts.sources = opts.sources or {}
      table.insert(opts.sources, {
        name = "lazydev",
        group_index = 0, -- set group index to 0 to skip loading LuaLS completions
      })
    end,
  },
  { -- optional blink completion source for require statements and module annotations
    "saghen/blink.cmp",
    opts = {
      sources = {
        -- add lazydev to your completion providers
        default = { "lazydev", "lsp", "path", "snippets", "buffer" },
        providers = {
          lazydev = {
            name = "LazyDev",
            module = "lazydev.integrations.blink",
            -- make lazydev completions top priority (see `:h blink.cmp`)
            score_offset = 100,
          },
        },
      },
    }
  }
  -- { "folke/neodev.nvim", enabled = false }, -- make sure to uninstall or disable neodev.nvim
}

The library option allows you to specify additional paths for LuaLS to include in the workspace. This is useful for providing types for third-party plugins or external libraries.

Supported formats for library entries:

• Absolute path: "~/projects/my-awesome-lib"
• Relative path: Resolved from the plugin directory (e.g., "lazy.nvim" or "LazyVim").
• Triggered loading: Use a table to load types only when specific conditions are met:
  • words: Load when specific words are found in the buffer (e.g., { path = "...", words = { "vim%.uv" } }).
  • mods: Load when a specific module is required (e.g., { path = "wezterm-types", mods = { "wezterm" } }).
  • files: Load when a specific filename is opened (e.g., { path = "...", files = { "xmake.lua" } }).

{
  "folke/lazydev.nvim",
  ft = "lua",
  opts = {
    library = {
      "~/projects/my-awesome-lib",
      "lazy.nvim",
      { path = "${3rd}/luv/library", words = { "vim%.uv" } },
      "LazyVim",
      { path = "LazyVim", words = { "LazyVim" } },
      { path = "wezterm-types", mods = { "wezterm" } },
      { path = "xmake-luals-addon/library", files = { "xmake.lua" } },
    },
  },
}