Configuring RobotCode as Language Server for Neovim

Neovim is an extensible Vim-based text editor. While there is no fully featured plugin of RobotCode that you can just install and use "as is" like for VS Code, it is still possible to leverage the Language Server provided by RobotCode to enable static analysis, go-to-definition, and other useful features.

This guide shows two alternatives to set up and configure your Neovim installation to use the RobotCode language server properly.

Common Prerequisites

To follow this guide, the reader is expected to already know the basics of

• installing and configuring Neovim
• adding plugins to Neovim
• Python virtual environments and how to create them

Regardless of the option you choose, using a language server in Neovim always requires to

• install the language server
• configure the language server
• enable the language server

This guide assumes a Neovim version >= 0.11 and uses the built-in LSP API.

The Common Pitfall When Using Mason and nvim-lspconfig

Two plugins are commonly used to install and configure LSP servers for Neovim, and are included in Neovim starter distributions like LazyVim:

• mason.nvim: a package manager that lets you install and manage LSP servers, including RobotCode
• nvim-lspconfig: quickstart configurations for LSP servers, including a configuration for RobotCode

While this combination sounds ideal, you will quickly experience import errors for third party libraries and custom keywords. Understanding why this happens is important to understand the differences of the alternatives discussed below.

Mason installs every package in a dedicated virtual environment, and makes the corresponding binary available globally from within Neovim.

nvim-lspconfig provides the following configuration:

return {
  cmd = { 'robotcode', 'language-server' },
  filetypes = { 'robot', 'resource' },
  root_markers = { 'robot.toml', 'pyproject.toml', 'Pipfile', '.git' },
  get_language_id = function(_, _)
    return 'robotframework'
  end,
}

This will start the language server by using the first robotcode binary found in PATH, which most likely is the one installed via Mason.

In this situation, RobotCode can only "see" the packages that are available in the virtual environment created by Mason, lacking all third party keyword libraries you may have installed in your project's virtual environment.

Setup Alternatives

If you want a simple LSP configuration and have RobotCode installed in your project anyway (or don't mind adding it), Option 1 is ideal.

If you prefer to install RobotCode globally via Mason, you need to tweak the LSP configuration a bit - see Option 2.

Option 1: Use Local Installation of RobotCode

The easiest way to run RobotCode in the context of your project's virtual environment is to add robotcode[languageserver] (or simply robotcode[all]) to your dependencies.

To configure the RobotCode language server, install nvim-lspconfig, or create the file manually under ~/.config/nvim/lsp/robotcode.lua:

---@brief
---
--- https://robotcode.io
---
--- RobotCode - Language Server Protocol implementation for Robot Framework.
return {
  cmd = { 'robotcode', 'language-server' },
  filetypes = { 'robot', 'resource' },
  root_markers = { 'robot.toml', 'pyproject.toml', 'Pipfile', '.git' },
  get_language_id = function(_, _)
    return 'robotframework'
  end,
}

Enable the LSP server by adding the following line to ~/.config/nvim/init.lua:

vim.lsp.enable("robotcode")

Before starting Neovim, make sure to first activate the virtual environment. If your virtual environment is created in the folder .venv:

Mac/Linux

source .venv/bin/activate
nvim

Windows PowerShell/pwsh

.venv\Scripts\activate.ps1
nvim

Windows CMD

.venv\Scripts\activate.bat
nvim

This ensures the robotcode binary from your project's environment is the first in PATH.

Option 2: Use Globally Installed RobotCode and Set PYTHONPATH

With this approach it is not necessary to install RobotCode in each and every project. You use Mason to install and update RobotCode globally for Neovim. The LSP configuration provides a helper function to set the PYTHONPATH variable so the globally installed RobotCode can import all your project specific libraries.

First, install RobotCode by executing :MasonInstall robotcode from within Neovim, or by using the Mason UI (:Mason).

Next, create the LSP configuration under ~/.config/nvim/lsp/robotcode.lua:

---@brief
---
--- https://robotcode.io
---
--- RobotCode - Language Server Protocol implementation for Robot Framework.

---@return string|nil
local function get_python_path()
  -- Search for the site-packages directory in the .venv folder.
  -- The folder structure differs between Windows and Unix,
  -- but this function handles both.
  local cwd = vim.uv.cwd()
  local project_site_packages = vim.fs.find("site-packages", {
    path = cwd .. "/.venv",
    type = "directory",
    limit = 1,
  })[1]

  if not project_site_packages then
    -- If the site-packages were not found, RobotCode will still work,
    -- but import errors will appear for third party libraries.
    vim.notify("RobotCode: project virtual environment not found.")
    return nil
  end

  local pythonpath = project_site_packages
  if vim.env.PYTHONPATH then
    -- Preserve original PYTHONPATH if already set by some other plugin
    local separator = vim.fn.has("win32") == 1 and ";" or ":"
    pythonpath = project_site_packages .. separator .. vim.env.PYTHONPATH
  end
  return pythonpath
end

local python_path = get_python_path()

---@type vim.lsp.Config
return {
  cmd = { "robotcode", "language-server" },
  cmd_env = python_path and { PYTHONPATH = python_path } or nil,
  filetypes = { "robot", "resource" },
  root_markers = { "robot.toml", "pyproject.toml", "Pipfile", ".git" },
  get_language_id = function(_, _)
    return "robotframework"
  end,
}

Note that get_python_path assumes that your virtual environment is created inside your project folder in a folder called .venv, which is a widespread standard but not necessarily true for some tools (e.g. pyenv).

Finally, enable the LSP server in ~/.config/nvim/init.lua:

vim.lsp.enable("robotcode")

This solution also works if you have some projects that have RobotCode installed locally. The downside is that you may have to tweak get_python_path if you don't follow the .venv folder convention.

Final Notes

Be aware that this setup only enables the features provided by the language server, i.e. diagnostics, completions, go-to-definition etc. Unlike the VS Code plugin this setup does not enable you to run or debug robot tests from within Neovim.