Kotlin Notebook Integration

The Kotlin Notebook IntelliJ Platform integration enables interactive development and experimentation with IntelliJ Platform APIs directly within a notebook environment. This integration allows developers to run IntelliJ Platform code within the active IDE runtime, removing traditional barriers associated with plugin project setup, compilation, and deployment.

Like Jupyter Notebooks, Kotlin Notebook provides an interactive platform for prototyping, testing, and exploring IntelliJ Platform functionality through executable code cells.

Getting Started

To begin using the IntelliJ Platform integration:

Create a new Kotlin Notebook file (.ipynb) in your project or as a scratch file using ⌘⇧N on macOS or Ctrl+Shift+N on Windows/Linux.
Important: Switch to Run in IDE Process mode in the notebook toolbar.
In the first code cell, declare:
%use intellij-platform

Once executed, the necessary IntelliJ Platform libraries are loaded into the Kotlin Notebook classpath, making them available for import in subsequent cells.

Core Features

UI Rendering

The integration enables direct rendering of UI components within notebook cells. When working with Kotlin UI DSL or standard Swing components, returning them as a response causes immediate rendering with full interactivity.

import com.intellij.ui.dsl.builder.panel
import java.awt.Dimension

panel {
  row {
    checkBox("Check me!")
  }
}.apply {
  size = Dimension(500, 200)
}

Use the runInEdt helper to ensure code execution on the Event Dispatch Thread (EDT) and handle exceptions gracefully:

runInEdt {
    // UI code that must run on EDT
}

Resource Management

The integration provides automatic resource management through the IntelliJ Platform's Disposer mechanism. A dedicated notebookDisposable variable allows registration of elements that need cleanup:

Disposer.register(notebookDisposable, myDisposable)

Disposer.register(notebookDisposable) {
  // ...
}

Plugin Loading

By default, only the core IntelliJ Platform is loaded into the classpath. To use other plugins (bundled or installed), explicitly load them using:

loadPlugins("Git4Idea", "com.intellij.java")

Extension Registration

Unlike traditional plugin development with plugin.xml, the integration provides programmatic extension registration:

registerExtension(extensionPointName, instance)

Global Variables

When the IntelliJ Platform integration is loaded, the following variables are automatically available in your Kotlin Notebook environment. These variables provide access to essential IDE components, configuration information, and management interfaces.

Variable	Type	Description
`idePath`	`Path`	Represents the resolved file system path to the IntelliJ Platform installation directory.
`ide`	`ProductInfoBasedIde`	Represents an IDE instance, which allows interacting with plugins and resolving their dependencies based on the IDE's configuration.
`notebookDisposable`	`Disposable`	Represents a disposable used for managing the IntelliJ Platform lifetime of the current notebook.
`notebookPluginDescriptor`	`PluginMainDescriptor`	Represents a plugin descriptor for the plugin created with Kotlin Notebook IntelliJ Platform integration.
`pluginManager`	`PluginManager`	Instance of the `PluginManager`, which allows accessing information about plugins and their states in the current IDE environment.
`pluginRepository`	`PluginRepository`	Instance of `PluginRepository`, responsible for managing plugins via the JetBrains Marketplace plugin repository.
`productInfo`	`ProductInfo`	Lazily initialized property containing current IntelliJ Platform product information.

Notebook Helpers

Function	Description
`error(message: String)`	Throws an exception with the specified message, which will be printed as the cell's output.
`loadPlugins(vararg pluginIds: String)`	Loads plugins installed in the current IDE into the script context based on their plugin IDs. This method also supports optionally loading plugin classes and class loaders.
`runInEdt(block: () -> Unit)`	Runs the given block in the Event Dispatch Thread (EDT). If an exception is thrown, it is displayed in the cell's output.

IntelliJ Platform Helpers

Function	Description
`currentProject()`	Returns the current open `Project` instance.
`currentEditor()`	Returns the current `FileEditor` instance or null if no editor is open.
`registerExtension(extensionPointName: ExtensionPointName<T>, instance: T)`	Registers an extension programmatically for the given extension point.
`registerExtension(extensionPointName: String, instance: T)`	Registers an extension programmatically for the given extension point.

Examples

Accessing IDE Information

println("IDE: ${productInfo.name}")
println("Version: ${productInfo.version}")
println("Build: ${productInfo.buildNumber}")

Loading and Using Plugins

loadPlugins("com.intellij.gradle")

import com.intellij.gradle.toolingExtension.util.GradleVersionUtil

GradleVersionUtil.isCurrentGradleAtLeast("8.13.0")

Registering Extension

import com.intellij.codeInsight.editorActions.CopyPastePreProcessor
import com.intellij.openapi.editor.Editor
import com.intellij.openapi.editor.RawText
import com.intellij.openapi.project.Project
import com.intellij.psi.PsiFile

class MyCopyPastePreProcessor : CopyPastePreProcessor {
  override fun preprocessOnCopy(
    file: PsiFile?,
    startOffsets: IntArray?,
    endOffsets: IntArray?,
    text: String?,
  ) = null

  override fun preprocessOnPaste(
    project: Project?,
    file: PsiFile?,
    editor: Editor?,
    text: String?,
    rawText: RawText?,
  ) = "Hello, World!"
}

registerExtension(CopyPastePreProcessor.EP_NAME, MyCopyPastePreProcessor())

Rendering Kotlin UI DSL Components

import com.intellij.ui.dsl.builder.panel
import java.awt.Dimension

panel {
  row {
    checkBox("Check me!")
      .comment("A comment for this checkbox")
  }
}.apply {
  size = Dimension(500, 200)
}

Rendering Dialog

import com.intellij.openapi.ui.Messages

runInEdt {
  Messages.showMessageDialog(
    null,
    "This is a modal dialog message",
    "Dialog Title",
    Messages.getInformationIcon()
  )
}

Creating Disposable Tool Window

import com.intellij.icons.AllIcons
import com.intellij.openapi.application.runInEdt
import com.intellij.openapi.util.Disposer
import com.intellij.openapi.wm.ToolWindowManager

val project = currentProject()
val toolWindowManager = ToolWindowManager.getInstance(project)

runInEdt {
  val toolWindow = toolWindowManager.getToolWindow("My Tool Window")
    ?: toolWindowManager.registerToolWindow("My Tool Window") {
      icon = AllIcons.General.Error
    }

  Disposer.register(notebookDisposable) {
    toolWindow.remove()
  }
}

23 July 2025