68 lines
3.4 KiB
Markdown
68 lines
3.4 KiB
Markdown
# Hello Plugin
|
|
|
|
Installable IdeA plugin example rebuilt from the public SDK types.
|
|
|
|
It exercises the current plugin primitives end to end:
|
|
|
|
- top-level menu: `Hello Plugin`;
|
|
- menu entry: `hello-plugin`;
|
|
- command: `hello-plugin`, returning readable feedback:
|
|
`{ status: "launched", taskId, state, message }` when it starts a background
|
|
task, or `{ status: "skipped", reason, message }` when a precondition is not
|
|
met;
|
|
- layout contribution: `hello-plugin.hello-world`, rendered by a React/JSX
|
|
component with hooks.
|
|
- plugin window: the menu command opens the layout through
|
|
`ctx.services.windows.open(...)` when services are available.
|
|
- plugin-owned storage: activation count, command run count and initialization flag;
|
|
- tooling capability: logs the focused workspace project when `ctx.services` is available.
|
|
- packaged command script: resolves `scripts/hello-task.mjs` from the official
|
|
`ctx.pluginRoot` and launches it with the project kept as the task working directory.
|
|
|
|
The source is intentionally split across multiple TypeScript modules:
|
|
|
|
- `src/index.ts` is the manifest entrypoint and imports relative ESM modules;
|
|
- `src/constants.ts` owns shared command/layout identifiers;
|
|
- `src/core/layout.tsx` and `src/core/workspace.ts` hold feature logic.
|
|
- `src/core/storage.ts` keeps plugin-owned counters and flags in `ctx.storage`.
|
|
- `scripts/hello-task.mjs` is a read-only runtime resource included in the archive.
|
|
|
|
The build uses plain `tsc`; it does not bundle the plugin into one file. The archive includes all
|
|
compiled `dist/**/*.js` files so IdeA can load `dist/index.js` and serve its package-relative imports
|
|
through `idea-plugin://`. React and ReactDOM are peer dependencies resolved to the host instance at
|
|
runtime. Other runtime imports from `node_modules` are outside this contract: vendor them as relative
|
|
files or bundle them into the plugin output before packaging.
|
|
|
|
```sh
|
|
npm run typecheck:examples
|
|
npm run package:hello-plugin
|
|
```
|
|
|
|
The installable archive is emitted at `examples/hello-plugin/build/hello-plugin-0.1.0.zip`.
|
|
It contains `idea-plugin.json` at the ZIP root, the compiled multi-file ESM output under `dist/`,
|
|
including `dist/index.js`, and the packaged handler under `scripts/hello-task.mjs`.
|
|
|
|
## Diagnostics
|
|
|
|
During activation the plugin logs:
|
|
|
|
- whether the command and layout runtime registries are available;
|
|
- whether plugin-owned storage is available;
|
|
- activation count and initialization state stored through `ctx.storage`;
|
|
- successful registration of the `hello-plugin` command;
|
|
- successful registration of the `hello-plugin.hello-world` layout;
|
|
- availability of the workspace service from the `tooling` runtime capability;
|
|
- best-effort workspace watch setup, including a non-fatal log when unavailable;
|
|
- the first layout render, including project/node identifiers;
|
|
- plugin window open/focus results from `ctx.services.windows.open(...)`.
|
|
|
|
During command invocation the plugin logs and returns structured feedback for
|
|
programmatic callers. The current human menu-click UI does not guarantee display
|
|
of that return value.
|
|
|
|
- skipped command feedback when no project or no `helloPlugin.ownerAgentId` is available;
|
|
- launched background command feedback when `helloPlugin.ownerAgentId` is configured;
|
|
|
|
These messages are intentionally small and stable so installation, bundle import, activation and
|
|
layout rendering failures can be separated quickly in IdeA logs/devtools.
|