Skip to content

Client Configuration#

Custom client configuration#

Note

The external LSP-* helper packages already come with their setting file and a client configuration and you don't need to add anything to the global LSP settings. This section is only relevant if you want to add a new client configuration for a server that doesn't have a corresponding helper package.

After you have installed a language server, the LSP settings need to be configured to enable communication between LSP and that server for suitable filetypes. LSP ships with configurations for a few language servers, but these need to be enabled before they will start. To globally enable a server, open the Command Palette and choose "LSP: Enable Language Server Globally". This will add "enabled": true to the corresponding language server setting under the "clients" key in your user-settings file for LSP. Your user-settings file is stored at Packages/User/LSP.sublime-settings and can be opened via "Preferences > Package Settings > LSP > Settings" from the menu or with the Preferences: LSP Settings command from the Command Palette. If your language server is missing or not configured correctly, you need to add/override further settings which are explained below.

Below is an example of the LSP.sublime-settings file with configurations for the Phpactor server.

{
  // General settings
  "show_diagnostics_panel_on_save": 0,

  // Language server configurations
  "clients": {
    "phpactor": {
      // enable this configuration
      "enabled": true,
      // the startup command -- what you would type in a terminal
      "command": ["PATH/TO/phpactor", "language-server"],
      // the selector that selects which type of buffers this language server attaches to
      "selector": "source.php"
    }
  }
}
Setting Description
enabled enables a language server (default is disabled)
command must be on PATH or specify a full path, add arguments (can be empty if starting manually, then TCP transport must be configured)
env dict of environment variables to be injected into the language server's process (eg. PYTHONPATH)
settings per-project settings (equivalent to VS Code's Workspace Settings)
initializationOptions options to send to the server at startup (rarely used)
selector This is the connection between your files and language servers. It's a selector that is matched against the current view's base scope. If the selector matches with the base scope of the the file, the associated language server is started. For more information, see https://www.sublimetext.com/docs/3/selectors.html
priority_selector Used to prioritize a certain language server when choosing which one to query on views with multiple servers active. Certain LSP actions have to pick which server to query and this setting can be used to decide which one to pick based on the current scopes at the cursor location. For example when having both HTML and PHP servers running on a PHP file, this can be used to give priority to the HTML one in HTML blocks and to PHP one otherwise. That would be done by setting "feature_selector" to text.html for HTML server and source.php to PHP server. Note: when the "feature_selector" is missing, it will be the same as the "document_selector".
tcp_port see instructions below
experimental_capabilities Turn on experimental capabilities of a language server. This is a dictionary and differs per language server
disabled_capabilities Disables specific capabilities of a language server. This is a dictionary with key being a capability key and being true. Refer to the ServerCapabilities structure in LSP capabilities to find capabilities that you might want to disable. Note that the value should be true rather than false for capabilites that you want to disable. For example: "signatureHelpProvider": true

You can figure out the scope of the current view with Tools > Developer > Show Scope.

Subprocesses#

A subprocess is always started. There is no support for connecting to a remote language server.

Transports#

Communication with a language server subprocess can be achieved in different ways. See the table below for what's possible.

Standard input/output (STDIO)#

The vast majority of language servers can communicate over stdio. To use stdio, leave out tcp_port and use only command in the client configuration.

TCP - localhost - subprocess acts as a TCP server#

Some language servers can also act as a TCP server accepting incoming TCP connections. So: the language server subprocess is started by this package, and the subprocess will then open a TCP listener port. The editor can then connect as a client and initiate the communication. To use this mode, set tcp_port to a positive number designating the port to connect to on localhost.

TCP - localhost - editor acts as a TCP server#

Some LSP servers instead expect the LSP client to act as a TCP server. The LSP server will then connect as a TCP client, after which the LSP client is expected to initiate the communication. To use this mode, set tcp_port to a negative number designating the port to bind to for accepting new TCP connections.

To use a fixed port number, use -X as the value for tcp_port, where X is the desired (positive) port number.

To select a random free port, use -1 as the value for tcp_port.

The port number can be inserted into the server's startup command in your client configuration by using the ${port} template variable. It will expand to the absolute value of the bound port.

Per-project overrides#

Global LSP settings (which currently are lsp_format_on_save and lsp_code_actions_on_save) can be overridden per-project in .sublime-project file:

{
  "folders":
  [
    {
      "path": "."
    }
  ],
  "settings": {
    "lsp_format_on_save": true,
  }
}

Also global language server settings can be added or overridden per-project by adding an LSP object within the settings object. A new server configurations can be added there or existing global configurations can be overridden (either fully or partially). Those can override server configurations defined within the clients key in LSP.sublime-settings or those provided by external helper packages.

Note: The settings and initializationOptions objects for server configurations will be merged with globally defined server configurations so it's possible to override only certain properties from those objects.

{
  "folders":
  [
    {
      "path": "."
    }
  ],
  "settings": {
    "LSP": {
      "jsts": {
        "enabled": false,
      },
      "LSP-eslint": {
        "settings": {
          "eslint.autoFixOnSave": true  // This property will be merged with original settings for
                                        // this client (potentially overriding original value).
        }
      }
    }
  }
}