Configuring Kotlin Support

This page describes developing plugins using the Kotlin programming language.

Advantages of Developing a Plugin in Kotlin

Using Kotlin to write plugins for the IntelliJ Platform is very similar to writing plugins in Java. Existing plugin developers can get started by converting boilerplate Java classes to their Kotlin equivalents by using the J2K converter (part of Kotlin plugin), and developers can easily mix and match Kotlin classes with their existing Java code.

In addition to null safety and type-safe builders, the Kotlin language offers many convenient features for plugin development, which make plugins easier to read and simpler to maintain. Much like Kotlin for Android, the IntelliJ Platform makes extensive use of callbacks, which are easy to express as lambdas in Kotlin.

Likewise, it is easy to customize the behavior of internal classes in the IntelliJ Platform using extensions. For example, it is common practice to guard logging statements to avoid the cost of parameter construction, leading to the following ceremony when using the log:

if (logger.isDebugEnabled()) {
  logger.debug("..."+expensiveComputation());
}

We can achieve the same result more succinctly in Kotlin, by declaring the following extension method:

inline fun Logger.debug(lazyMessage: () -> String) {
  if (isDebugEnabled) {
    debug(lazyMessage())
  }
}

Now we can directly write:

logger.debug { "..." + expensiveComputation() }

to receive all the benefits of lightweight logging while reducing the code verbosity.

With practice, you will be able to recognize many idioms in the IntelliJ Platform that can be simplified with Kotlin.

UI Forms in Kotlin

The IntelliJ Platform provides the type safe DSL allowing to build UI forms in a declarative way.

Adding Kotlin Support

IntelliJ IDEA bundles the necessary Kotlin plugin, requiring no further configuration. For detailed instructions, please refer to the Kotlin documentation.

Kotlin Gradle Plugin

Adding Kotlin source files compilation support to the Gradle-based project requires adding and configuring the Kotlin JVM Gradle plugin.

See the build.gradle.kts from kotlin_demo sample plugin:

plugins {
  id("java")
  id("org.jetbrains.intellij") version "1.15.0"
  id("org.jetbrains.kotlin.jvm") version "1.9.10"
}

group = "org.intellij.sdk"
version = "2.0.0"

repositories {
  mavenCentral()
}

java {
  sourceCompatibility = JavaVersion.VERSION_17
}

// See https://plugins.jetbrains.com/docs/intellij/tools-gradle-intellij-plugin.html
intellij {
  version.set("2022.3.3")
}

tasks {
  buildSearchableOptions {
    enabled = false
  }

  patchPluginXml {
    version.set("${project.version}")
    sinceBuild.set("223")
    untilBuild.set("232.*")
  }

  compileKotlin {
    kotlinOptions.jvmTarget = "17"
  }

  compileTestKotlin {
    kotlinOptions.jvmTarget = "17"
  }
}

Kotlin Standard Library

Since Kotlin 1.4, a dependency on the standard library stdlib is added automatically (API Docs). In most cases, it is not necessary to include it in the plugin distribution as the platform already bundles it.

To opt out, add this line in gradle.properties:

kotlin.stdlib.default.dependency = false

The presence of this Gradle property is checked by the Gradle IntelliJ Plugin with the verifyPluginConfiguration. If the property is not present, a warning will be reported during the plugin configuration verification, as it is a common problem when Kotlin stdlib gets bundled within the plugin archive. If it is expected to make Kotlin stdlib present in the final archive, explicitly specify it with kotlin.stdlib.default.dependency = true.

If a plugin supports multiple platform versions, it must either target the lowest bundled stdlib version or provide the specific version in plugin distribution.

IntelliJ Platform version	Bundled `stdlib` version
2023.2	1.8.20
2023.1	1.8.0
2022.3	1.7.0
2022.2	1.6.21
2022.1	1.6.20
2021.3	1.5.10
2021.2	1.5.10
2021.1	1.4.32
2020.3	1.4.0
2020.2	1.3.70
2020.1	1.3.70
2019.3	1.3.31
2019.2	1.3.3
2019.1	1.3.11

See Dependency on the standard library for more details.

Incremental compilation

The Kotlin Gradle plugin supports incremental compilation, which allows tracking changes in the source files so the compiler handles only updated code.

Remove additional kotlin.incremental.useClasspathSnapshot=false property in gradle.properties if present.

The Kotlin 1.8.20 release has a new incremental compilation approach enabled by default. Unfortunately, it is not compatible with the IntelliJ Platform — when reading large JAR files (like app.jar or 3rd-party-rt.jar), leading to the Out of Memory exception:

Execution failed for task ':compileKotlin'.
> Failed to transform app.jar to match attributes {artifactType=classpath-entry-snapshot, org.gradle.libraryelements=jar, org.gradle.usage=java-runtime}.
   > Execution failed for ClasspathEntrySnapshotTransform: .../lib/app.jar.
      > Java heap space

To avoid this exception, add the following line to the gradle.properties:

kotlin.incremental.useClasspathSnapshot=false

You can find the current state of the issue in KT-57757.

Other Bundled Kotlin Libraries

Please see Third-Party Software and Licenses.

Plugin Implementation Notes

Do not use "object" but "class"

Plugins may use Kotlin classes (class keyword) to implement declarations in the plugin configuration file. When registering an extension, the platform uses a dependency injection framework to instantiate these classes at runtime. For this reason, plugins must not use Kotlin objects (object keyword) to implement any plugin.xml declarations. Managing the lifecycle of extensions is the platform responsibility and instantiating these classes as Kotlin singletons may cause issues.

Problems are highlighted via these inspections (2023.2):

Plugin DevKit | Code | Kotlin object registered as extension for Kotlin code
Plugin DevKit | Plugin descriptor | Extension class is a Kotlin object for plugin.xml

Do not use "companion object" in extensions

Kotlin companion object is always created once you try to load its containing class, and extension point implementations are supposed to be cheap to create. To avoid unnecessary classloading (and thus slowdown in IDE startup), companion object in extensions must only contain simple constants or logger. Anything else must be a top-level declaration or stored in an object.

Use inspection Plugin DevKit | Code | Companion object in extensions to highlight such problems (2023.3).

Kotlin Code FAQ

How to shorten references

Example Plugins Implemented in Kotlin

There are many open-source Kotlin plugins built on the IntelliJ Platform. For a readily available source of up-to-date examples of plugins implemented in Kotlin, developers may look to these projects for inspiration:

Last modified: 06 September 2023