IntelliJ Platform Plugin SDK Help

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.

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.

LSP Plugin Setup

The plugin must target IntelliJ IDEA Ultimate version 2023.2 or later.

Gradle

Relevant build.gradle.kts configuration:

plugins { id("org.jetbrains.intellij.platform") version "2.0.0-rc1" } repositories { mavenCentral() intellijPlatform { defaultRepositories() } } dependencies { intellijPlatform { intellijIdeaUltimate("2024.1.4") } }

Upgrade the Gradle IntelliJ Plugin to the latest version. It will attach the LSP API sources and code documentation to the project.

Relevant build.gradle.kts configuration:

plugins { // ... id("org.jetbrains.intellij") version "1.17.4" } intellij { version = "2024.1.4" type = "IU" }

For projects based on the IntelliJ Platform Plugin Template, update the Gradle IntelliJ Plugin to the latest version, and amend the values in gradle.properties accordingly.

plugin.xml

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

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

IDE Setup

The LSP API sources are bundled in IntelliJ IDEA Ultimate and can be found within the $IDEA_INSTALLATION$/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

2023.3

2023.3.2

Basic Implementation

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

Minimal LSP Plugin Setup

  1. 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.

  2. Register it as a com.intellij.platform.lsp.serverSupportProvider Extension Point (EP):

  3. 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

    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:

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

    Last modified: 25 July 2024