VimScript Language Server

Common errors

• Error: "command like `fixdel` in vimrc which neovim does not support will report error."

  cause The `isNeovim` option is set to `true` in `initializationOptions`, but your VimScript contains commands not recognized by Neovim.
  fix Set `isNeovim: false` in your LSP client's configuration for the server, or modify your VimScript to remove/handle Neovim-incompatible commands.

• LSP features (completion, diagnostics) are slow or unresponsive.

  cause The default indexing configuration (`initializationOptions.indexes`) is not optimized for your project size or system resources.
  fix Increase `initializationOptions.indexes.count` (e.g., to 5 or more) and decrease `initializationOptions.indexes.gap` (e.g., to 50 or less) to speed up file indexing.

Warnings

• breaking Major version `v2.0.0` was released without detailed breaking changes noted in the provided changelog. Users upgrading from v1.x may encounter unexpected behavior or require configuration adjustments.
  Fix: Review the project's GitHub release notes or issues for `v2.0.0` for specific breaking changes and update configurations accordingly. Test thoroughly after upgrading.
• gotcha Setting `initializationOptions.isNeovim: true` can cause errors if your VimScript files contain commands that are specific to Vim and not supported by Neovim (e.g., `fixdel`).
  Fix: If you encounter errors related to unsupported commands, either set `isNeovim: false` in your configuration or remove/guard the problematic commands in your VimScript files.
• gotcha Performance issues such as slow completion or diagnostics can occur, especially in large projects, due to default indexing settings.
  Fix: Adjust the `initializationOptions.indexes.gap` (indexing time gap in ms, lower for faster) and `initializationOptions.indexes.count` (number of files to index concurrently, higher for faster) to optimize performance for your environment.

Install

• npm install vim-language-server npm
• yarn add vim-language-server yarn
• pnpm add vim-language-server pnpm

Imports

• vim-language-server (CLI)
  wrong:

  import { startServer } from 'vim-language-server'

  correct:

  npm install -g vim-language-server
  vim-language-server --stdio

  This package is primarily a command-line executable. Developers interact with it by installing it globally and launching it via a Language Server Protocol (LSP) client or directly as a CLI process. Direct programmatic imports for application logic are not the intended use case.
• module path for LSP clients
  wrong:

  require('/path/to/vim-language-server/bin/index.js')

  correct:

  "module": "/path/to/vim-language-server/bin/index.js"

  LSP clients like `coc.nvim` can be configured to launch the server by specifying the direct path to its main executable script, `bin/index.js`, for Node.js IPC communication. This is a configuration setting, not a direct JavaScript `require` or `import` for programmatic use within an application.
• command for LSP clients

  "command": "vim-language-server"

  Alternatively, LSP clients can execute the globally installed `vim-language-server` command directly from the system's PATH for standard I/O (stdio) communication. This is also a configuration setting within the LSP client.

Quickstart

Demonstrates global installation via npm and a comprehensive `coc.nvim` configuration example for the VimScript Language Server, showing both Node.js IPC and stdio setup options.

{
  // First, install the language server globally:
  // npm install -g vim-language-server

  // To use with coc.nvim, add the following to your coc-settings.json:
  // This configuration tells coc.nvim how to launch and interact with the server.
  "languageserver": {
    "vimls": {
      // Option 1: Using Node.js IPC (Inter-Process Communication) for potentially faster communication.
      // Ensure the path to index.js is correct for your installation. 
      // You can find it by running `npm root -g` and then looking inside `vim-language-server/bin/index.js`.
      "module": "/usr/local/lib/node_modules/vim-language-server/bin/index.js", // Example path, adjust as needed
      "args": ["--node-ipc"],

      // Option 2 (alternative to "module"): Using standard I/O for communication.
      // This assumes `vim-language-server` is in your system's PATH.
      // "command": "vim-language-server",
      // "args": ["--stdio"],

      "initializationOptions": {
        "isNeovim": true, // Set to true if you are using Neovim, false for Vim8+
        "iskeyword": "@,48-57,_,192-255,-#", // Customize Vim's `iskeyword` option
        "vimruntime": "$VIMRUNTIME",         // Path to your $VIMRUNTIME directory
        "runtimepath": "~/.config/nvim,~/.vim", // Comma-separated list of runtime paths
        "diagnostic": { "enable": true }, // Enable diagnostics
        "indexes": {
          "runtimepath": true, // Index vim files from runtimepath for suggestions
          "gap": 50,           // Indexing time gap in ms
          "count": 5           // Number of files to index concurrently
        },
        "suggest": {
          "fromVimruntime": true,
          "fromRuntimepath": true
        }
      },
      "filetypes": [ "vim" ] // Specify file types this server should handle
    }
  }
}