IdeaSDK/docs/activation-context.md

Activation And Context

The plugin entrypoint exports activate(ctx).

import type { ActivateContext, IdeAPluginModule } from "@idea/plugin-sdk";

export function activate(ctx: ActivateContext): void {
  ctx.logger.info("activated", {
    pluginId: ctx.pluginId,
    pluginRoot: ctx.pluginRoot
  });
}

export default { activate } satisfies IdeAPluginModule;

IdeA accepts either a named activate export or a default export containing activate.

Activation Scope

activationScope defaults to "app". App-scoped plugins activate during app bootstrap. Project-scoped plugins are kept pending until a project is focused, then activated once for the app session.

Choose "project" only when activate(ctx) must immediately read project state. Menu commands and layouts can usually stay app-scoped and check for a focused project at invocation/render time.

Context Fields

• pluginId: host-provided plugin identity.
• pluginRoot: absolute host-local path to the active installed plugin package.
• logger: debug, info, warn, error.
• subscriptions: push disposables returned by command/layout/watch registrations.
• commands: command registry for declared menu commands.
• layouts: layout registry for declared layout types.
• menu: marker for the plugin-owned menu surface.
• storage: plugin-owned persistent key/value storage.
• services: public host service facade for plugins declaring ui or tooling capabilities.

The context never exposes internal IdeA gateways or Tauri commands. Use ctx.services and the registration APIs instead.

pluginRoot identifies the committed package currently loaded by IdeA. It is not the original source directory or archive path and may change after reinstall. Treat it as read-only, do not persist it, and resolve packaged scripts/assets under it only while the plugin is active. Workspace services remain confined to project-owned paths.

Disposal

Push every returned disposable to ctx.subscriptions:

const disposable = ctx.commands?.registerCommand("com.example.run", run);
if (disposable) ctx.subscriptions.push(disposable);

IdeA disposes these handles best-effort when the plugin is unloaded or the app session ends.

Storage

Use ctx.storage for plugin-owned counters, flags, preferences and small caches. Use workspace/config services only for project-owned files or configuration that the user expects to see in the project.