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

An IdeA agent can install a development plugin directory only when that agent has the plugin administration MCP tool explicitly allowed. The public tool is idea_plugin_install_from_directory:

{
  "path": "relative/path/to/hello-plugin",
  "expectedPluginId": "com.example.hello-plugin"
}

The path must resolve under the requester's project root. This installs the directory as the recorded development source for later reloads.

After source edits, rebuild the plugin output and 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.

On reload, plugin_reloaded tells the UI to rebuild the plugin runtime registry. When the package content hash changes, plugin ESM URLs change and React layout components are loaded from the new package. Existing plugin layout instances may remount and lose local React state; host-persisted layout state written through setState remains the durable state channel.

JavaScript module instances cannot be forcibly removed from the browser ESM cache. Register handlers, layouts, watches and subscriptions through the SDK registries and push disposable side effects into ctx.subscriptions; global module side effects can otherwise survive a reload. If the package hash did not change, the reload is idempotent and may reuse the same module instance.

IdeA runtime plugin installation is separate from Codex plugin/skill discovery. See Codex Skills And IdeA Plugins.