Language Server Protocol (LSP)

The Language Server Protocol (LSP) is an open-standard protocol developed by Microsoft. It enables communication between development tools and Language Servers. Language Servers can provide language-specific features such as code completion, documentation, and formatting, which is far easier than implementing language support from scratch. It also reduces the need for constant maintenance and tracking of changes in relevant languages and tools, making it easier to bring consistent language support to various development environments.

However, the canonical Custom Language Support provided by IntelliJ Platform still offers a wider range of integration with IDE features than handling and presenting data provided by a Language Server. Therefore, the LSP approach shouldn't be considered as a replacement for the existing language API, but rather as an added value.

Supported IDEs

The integration with the Language Server Protocol is created as an extension to the paid IntelliJ-based IDEs. Therefore, plugins using Language Server integration are not available in Community releases of JetBrains products and Android Studio from Google.

Starting with the 2023.2 release cycle, the LSP API is publicly available as part of the IntelliJ Platform in the following IDEs: IntelliJ IDEA Ultimate, WebStorm, PhpStorm, PyCharm Professional, DataSpell, RubyMine, CLion, Aqua, DataGrip, GoLand, Rider, and RustRover.

Plugin Configuration

To use the LSP API in a third-party plugin based on the Gradle IntelliJ Plugin, it is required to upgrade the Gradle IntelliJ Plugin to the latest version available. This plugin will attach the LSP API sources and code documentation to the project.

As LSP became available in the 2023.2 EAP7 of IntelliJ-based IDEs, the plugin must target IntelliJ IDEA Ultimate version 2023.2 or later.

Example build.gradle.kts configuration:

plugins {
  // ...
  id("org.jetbrains.intellij") version "1.17.3"
}

intellij {
  version = "2024.1"
  type = "IU"
}

For projects based on the IntelliJ Platform Plugin Template, update the Gradle IntelliJ Plugin to the latest version, and amend the gradle.properties file as follows:

platformType = IU
platformVersion = 2024.1

The plugin.xml configuration file needs to specify the dependency on the IntelliJ IDEA Ultimate module:

<idea-plugin>
   <!-- ... -->
   <depends>com.intellij.modules.ultimate</depends>
</idea-plugin>

The LSP API sources are bundled in IntelliJ IDEA Ultimate and can be found within the [IDE]/lib/src/src_lsp-openapi.zip archive.

Supported Features

The LSP support provided by the IntelliJ Platform covers the following features for these releases:

2023.2

Errors and warnings highlighting textDocument/publishDiagnostics
Quick fixes for errors and warnings (textDocument/codeAction)
Code completion (textDocument/completion)
Go to Declaration (textDocument/definition)

2023.3

Intention actions (textDocument/codeAction)
Code formatting (textDocument/formatting)

2023.3.2

Quick documentation (textDocument/hover)

Basic Implementation

As a reference, check out the Prisma ORM open-source plugin implementation: Prisma ORM LSP

Minimal LSP Plugin Setup

Implement LspServerSupportProvider and within the LspServerSupportProvider.fileOpened() method, spin up the relevant LSP server descriptor, which can decide if the given file is supported by using the LspServerDescriptor.isSupportedFile() check method.
Register it as a com.intellij.platform.lsp.serverSupportProvider Extension Point (EP):
Tell how to start the server by implementing LspServerDescriptor.createCommandLine().

import com.intellij.platform.lsp.api.LspServerSupportProvider
import com.intellij.platform.lsp.api.ProjectWideLspServerDescriptor

internal class FooLspServerSupportProvider : LspServerSupportProvider {
  override fun fileOpened(project: Project, file: VirtualFile, serverStarter: LspServerStarter) {
    if (file.extension == "foo") {
      serverStarter.ensureServerStarted(FooLspServerDescriptor(project))
    }
  }
}

private class FooLspServerDescriptor(project: Project) : ProjectWideLspServerDescriptor(project, "Foo") {
  override fun isSupportedFile(file: VirtualFile) = file.extension == "foo"
  override fun createCommandLine() = GeneralCommandLine("foo", "--stdio")
}

Status Bar Integration

Since 2024.1, a dedicated Language Services status bar widget is available to monitor the status of all LSP servers. Override LspServerSupportProvider.createLspServerWidgetItem() to provide a custom icon and link to Settings page (if available).

override fun getLspServerWidgetItem(lspServer: LspServer,
                                    currentFile: VirtualFile?) =
  LspServerWidgetItem(lspServer, currentFile,
                      FooIcons.PluginIcon, FooConfigurable::class.java)

If there are configuration problems preventing from starting an LSP server, the plugin can provide a widget item with an error and give the user a hint how to fix the problem.

Language Server Integration

Language Server is a separate process that analyzes source code and provides language-specific features to development tools. When creating a plugin that uses LSP within the IDE, there are two possibilities for providing a Language Server to end-users:

Bundle a Language Server implementation binary as a resource delivered with a plugin.
Provide a possibility for users to define the location of the Language Server binary in their environment.

The Prisma ORM plugin presents the first approach, which distributes the prisma-language-server.js script and uses a local Node.js interpreter to run it.

For more complex cases, the plugin may request to provide a detailed configuration with a dedicated Settings implementation.

Customization

To fine-tune or disable the implementation of LSP-based features, plugins may override the corresponding properties of the LspServerDescriptor class. See the property documentation for more details.

Since 2023.2:

lspGoToDefinitionSupport
lspCompletionSupport
lspDiagnosticsSupport
lspCodeActionsSupport
lspCommandsSupport

Since 2023.3:

lspFormattingSupport
lspHoverSupport

To handle custom (undocumented) requests and notifications from the LSP server, override LspServerDescriptor.createLsp4jClient property and the Lsp4jClient class according to their documentation.

To send custom (undocumented) requests and notifications to the LSP server, override LspServerDescriptor.lsp4jServerClass property and implement the LspClientNotification and/or LspRequest classes. The documentation in the source code includes implementation examples.

See bundled LSP API source code and its documentation for more information.

Troubleshooting

All the IDE and LSP server communication logs are passed to the IDE log file.

To include them, add the following entry to the Help | Diagnostic Tools | Debug Log Settings… configuration dialog:

#com.intellij.platform.lsp

For more information, see the Logging section.

Integration Overview

Integrating the Language Server Protocol (LSP) into a plugin for IntelliJ-based IDEs involves a trade-off between simple and fast language support and a complex custom language support plugin with IDE capabilities.

When considering the LSP-based approach, it is important to assess the following criteria for providing a Language Server to end users:

OS dependency of the Language Server.
Availability of the latest version online.
Compatibility with breaking changes between versions.
Feasibility of requesting the user to provide the Language Server binary path.

Sample Plugins

The following open-source plugins make use of LSP:

Prisma ORM

Explore third-party plugins using LSP on IntelliJ Platform Explorer.

Last modified: 04 March 2024