IdeaSDK/docs/packaging-distribution.md

Packaging And Distribution

A plugin archive is a ZIP file whose root contains idea-plugin.json.

hello-plugin-0.1.0.zip
├── idea-plugin.json
├── README.md
└── dist/
    ├── index.js
    ├── constants.js
    └── core/
        ├── layout.js
        ├── storage.js
        └── workspace.js

The manifest main field must point to an emitted file inside the archive:

{
  "main": "dist/index.js"
}

Module Resolution

IdeA loads main as ESM and serves package-relative imports from the plugin package. This is supported:

import { Dashboard } from "./core/layout.js";

For React, import bare host modules normally:

import { useState } from "react";
import { jsx } from "react/jsx-runtime";

IdeA resolves React/ReactDOM bare imports to the host instance. Other bare dependencies are not host-resolved. Bundle or vendor third-party dependencies other than React/ReactDOM into package-relative files.

TypeScript Build

The hello plugin uses plain tsc:

npm run build
npm run build:hello-plugin

For React layouts, configure JSX:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

Archive Build

The SDK example can be packaged with:

npm run package:hello-plugin

The resulting archive has no wrapping parent directory and is ready for IdeA's plugin installer.

Hot Reload During Development

Install the plugin from a directory when you want IdeA to hot-reload changes without restarting the app.

In IdeA, open Paramètres > Plugins, choose Installer depuis un dossier…, and select the plugin source directory. That directory must contain idea-plugin.json at its root, and the manifest main field must point to the built entrypoint that exists inside the same directory, for example dist/index.js.

hello-plugin/
├── idea-plugin.json
├── package.json
└── dist/
    ├── index.js
    └── core/
        └── layout.js

After editing plugin source files, rebuild the plugin output first:

npm run build

Then ask an IdeA agent that has the plugin administration tool available to run idea_plugin_reload with the installed plugin id:

{
  "pluginId": "com.example.hello-plugin"
}

The reload uses the recorded directory source from the plugin registry. It re-reads and validates the manifest, recalculates the package hash, updates the installed package, emits plugin_reloaded, and reconciles plugin MCP servers. It does not accept an arbitrary path at reload time; install from the intended development directory first.

Do not install from the ZIP archive for a development loop that needs hot reload. Archive installs are fixed package snapshots. They are appropriate for distribution, but the reload command is only defined for plugins installed from a directory source.

Current limitation: backend registry state and plugin MCP/tool contributions are reloaded without restarting IdeA. Frontend React contributions that are already loaded in the current UI session may keep their existing module instance until the relevant plugin surface is recreated or the app session is restarted.