Adapting Your JetBrains Plugin for Remote Development: A Step-by-Step Guide

Introduction

Remote development is changing how we build plugins for JetBrains IDEs. The IDE no longer runs as a single process on one machine; instead, users interact with a frontend client while the backend operates on another machine, in Docker, or in the cloud. This split-mode architecture enhances flexibility, security, and power for development workflows. For plugin developers, this means you must think not just about what your plugin does, but where each part executes. Without proper adaptation, UI components, typing features, and latency-sensitive code can become sluggish or break. This guide walks you through making your plugin ready for remote development, step by step.

What You Need

• JetBrains IDE (e.g., IntelliJ IDEA) with support for remote development (2023.1 or later).
• Plugin development environment: Gradle setup with IntelliJ Platform Plugin template.
• Basic understanding of plugin architecture, client-server concepts, and JetBrains Platform APIs.
• Access to resources: video overview, plugin template, documentation, and forum (links in tips).

Step-by-Step Guide

1. Step 1: Understand Split Mode Architecture

   Before coding, grasp how split mode works. The IDE becomes two processes: the frontend (client, local) handles UI and user input; the backend (server, remote) runs core logic, indexing, and compilation. They communicate via a remote protocol. Your plugin must separate code accordingly: frontend (e.g., UI panels, tool windows) should run on the client; backend (e.g., analysis, refactoring) on the server. Shared code (e.g., data models) can stay common but must be serializable.

2. Step 2: Assess Your Plugin’s Components

   List every feature of your plugin. Identify which parts are UI-related (e.g., tool windows, notifications, settings) and which are computation-heavy (e.g., code inspections, quick fixes). Also note any typing or completion features—these are latency-sensitive and need careful placement. For each component, decide: frontend, backend, or shared. Use a table or diagram to map dependencies.

3. Step 3: Structure Plugin Modules Properly

   Create a multi-module project following the recommended layout: a backend module (server-side), a frontend module (client-side), and a shared module (common code). For example, using Gradle, define three subprojects. The shared module contains interfaces and data transfer objects (DTOs). Backend module implements backend services; frontend module handles UI and calls backend via remoting (e.g., using RemoteProcessService). Use the official plugin template as a starting point—it includes correct module structures.

4. Step 4: Move Code to the Appropriate Side

   Refactor your plugin: backend code goes into the backend module—business logic, file system access, and actions that don’t need direct UI. Frontend code stays in the frontend module—tool windows, panels, dialogs, and user input handling. Shared code in the shared module includes constants, enums, and interfaces. Ensure that backend code does not depend on frontend classes. Use dependency injection or service locators to access backend from frontend.

5. Step 5: Connect Frontend and Backend

   Define communication channels. In JetBrains remote development, you typically use RPC (remote procedure calls) or a MessageBus that works across processes. Register backend services that can be called from the frontend. For example, create a MyPluginService interface in shared module, implement it in backend module, and register as a plugin service. The frontend can obtain a proxy to that service via RemoteProcessService. Ensure all parameters and return types are serializable (e.g., use @Serializable or implement Serializable). Test the connection in both split and local modes.

   

6. Step 6: Run and Debug in Split Mode

   Set up a remote development environment: launch the IDE backend on a remote machine (or Docker) and connect a local frontend client. Use the Remote Development tool window in IntelliJ. Deploy your plugin to both sides. Debug using remote debug configurations, attaching to the backend process. Monitor logs for any split-mode-specific errors (e.g., class not found, serialization issues). Verify UI responsiveness and typing latency.

7. Step 7: Test Thoroughly

   Write tests for each module separately. Use mock for the remote connection. Run integration tests in a split-mode environment (e.g., using GitHub Actions with Docker). Check that features work identically in monolithic IDE (local) and split-mode. Pay attention to timing—remote calls add latency, so avoid blocking the UI. Use @Backgroundable tasks for long operations. Also test edge cases: disconnection, slow network, and reconnection.

Tips for Success

• Leverage the official resources: Watch the video overview for a high-level understanding. Use the plugin template with proper module structures—it saves weeks of setup.
• Prioritize latency-sensitive features: Autocompletion and inspections must remain snappy. Offload heavy computation to backend and update UI asynchronously.
• Keep shared code minimal: Only include interfaces and DTOs. Avoid complex logic in shared module to prevent unnecessary serialization overhead.
• Test in both modes early: Don’t wait until the end; run your plugin locally and in split mode from step 3 to catch issues like class loading conflicts.
• Ask the community: The JetBrains Platform forum is active. Search for existing answers or post your questions.
• Document your architecture: For future maintainers, note which parts run where. Use comments or a readme file.
• Optimize for success: Consider using RemoteAction for actions that need to trigger backend logic. And always design for local mode fallback.