🌙 coc-luals

coc-luals is a coc.nvim extension powered by lua-language-server (LuaLS). It provides the full feature set of LuaLS/vscode-lua, along with dedicated Neovim Lua development utilities like dynamic library imports and integrated addon management.

✨ Features

• 🎯 Full LuaLS Support: Complete language server features and configuration schema, using official binaries extracted from LuaLS/vscode-lua.
• ⚡ Auto-Download: Automatically downloads prebuilt binaries on first launch (Windows, macOS, Linux), or point to your own binary.
• 🧩 Neovim Lua Development: Auto $VIMRUNTIME loading, on-demand plugin library imports on require('...'), and quickfix code actions.
• 📦 Addon Manager: Browse, install, and toggle official LuaLS/LLS-Addons directly in coc.nvim via :CocList lls_addons.

📦 Installation

Install via coc.nvim:

:CocInstall coc-luals

💡 On first launch, if lua-language-server is not found, coc-luals prompts to download the prebuilt binary automatically.

📖 Neovim Lua Development

Designed for editing Neovim configurations and plugins:

• Automatic $VIMRUNTIME: Provides autocompletion and documentation for Neovim runtime APIs (vim.api.*, vim.fn.*, etc.).
• Runtime Plugin Completion: Autocomplete suggestions include modules from installed runtime plugins.
• Dynamic Library Import: Instead of adding every installed plugin to workspace.library at startup, definitions are loaded on-the-fly when used.
• Code Action: Offers Import library '<name>' to workspace on unimported module calls.

Configuration

// In :CocConfig
{
  // Enable Neovim Lua development support (auto-imports $VIMRUNTIME)
  "luals.nvimLua.enable": true,

  // Optional: pre-import specific plugin libraries
  "luals.nvimLua.library": [
    "nvim-treesitter",
    "plenary.nvim"
  ]
}

🧩 Addon Manager

Manage addons from LuaLS/LLS-Addons (e.g. definitions and annotations for Busted, LÖVE, OpenResty, Hammerspoon).

Open the addon list:

:CocList lls_addons
" or
:CocCommand lua.openAddonManager

Status Indicators

| Indicator | Status | | :-------: | :----- | | [+] | Enabled in workspace | | [*] | Installed (disabled) | | [-] | Available (not installed) |

Actions

• <CR>: Enable addon (downloads and installs automatically if not yet present).
• <Tab>: Open action menu:
  • enable: Enable addon and apply workspace settings
  • disable: Disable addon and revert settings
  • install: Download and cache addon
  • uninstall: Remove local addon cache
  • view on github: Open repository in browser

🛠️ Server Executable

• Default: Uses official release binaries extracted from LuaLS/vscode-lua.
• Custom Executable / Directory: To use a system package or custom build:

  {
    "Lua.misc.executablePath": "lua-language-server"
    // or
    // "luals.serverDir": "/path/to/lua-language-server"
  }

⌨️ Commands

| Command | Description | | :------ | :---------- | | lua.install | Install or update server binary | | lua.restart | Restart Lua language server and extension | | lua.checkUpdate | Check for server binary updates | | lua.showVersion | Show current Lua Language Server version | | lua.showUsage | Display server status and resource usage | | lua.showChangelog | Open and read server changelog | | lua.openAddonManager | Open the Addon Manager list | | lua.reloadFFIMeta | Reload LuaJIT FFI metadata definitions |

⚙️ Settings

coc-luals supports all upstream LuaLS configuration options.

• 📖 Full Settings Reference
• 🐧 Config Examples for Distributions (e.g. NixOS)

📄 License

MIT © wongxy