Skip to main content
The plugin API has one version number: the version of the WIT package in wit/ (openidea:plugin@1.5.0 on main). The host’s engine version and the SDK’s API_VERSION always agree with it, and the SDK carries an identical copy of the WIT files.
The plugin system is a preview. The compatibility rules below hold for released 1.x versions; what is still unreleased on main can change before it ships.

​
Versions

The full list of what each version added is in plugins/README.md.

​
Declaring what you need

engines.openidea in plugin.toml is a semver requirement on the plugin API:
  • The IDE refuses to install or load a package whose requirement does not match its own API version.
  • Use the lowest version that has everything you use. ^1.0 loads in every 1.x IDE.
  • Some manifest features enforce a minimum: installing and openidea-plugin check refuse a manifest that uses them while still admitting an older API.

​
The component’s own version

Besides the manifest, the IDE reads the API version a component was built for: the highest version among its openidea:plugin/* imports and exports. That is the version of the SDK (or WIT files) it was compiled against.
  • Installing and openidea-plugin check refuse a component of another major version, or of a newer minor than the IDE implements, with a message to update the IDE or rebuild with an older SDK.
  • They also link the component against the IDE. A component that imports a function the IDE lacks under the same version (built from unreleased WIT) is refused too.
  • check prints it: code: dist/plugin.wasm (…, plugin API 1.4).
So build against the SDK of the oldest IDE release you want to support. A plugin made by openidea-plugin new depends on the SDK at the tool’s release tag:
Change the tag to build against a later API. A component built from main uses the unreleased API and will not load in released IDEs. In a marketplace index, each version’s engine is the manifest’s requirement narrowed to the component’s API (for example ^1.0, ^1.4). A plugin can be listed in several versions; each IDE is offered the newest one it can load, and a plugin with none is shown as incompatible with the API it needs.

​
Compatibility rules

wasmtime links components by semver: a component importing openidea:plugin/x@1.0.0 links against a host that defines @1.4.0. Function types must match exactly, though, so a released 1.x only grows:
  1. Released types and signatures never change. No new record fields, variant or enum cases, renames or parameters. New things get new types and new functions. Sets that keep growing (completion kinds, icons, event kinds, …) are strings, and growing variants have an other case carrying a kind and JSON data, so older plugins and IDEs can pass them through.
  2. Host interfaces (imports) may gain functions and interfaces. Older components don’t import them.
  3. Plugin interfaces (exports) never gain functions once released. New plugin-side features get new interfaces in new optional worlds.
  4. The host checks each component’s API version as described above.
  5. One version number across wit/, the host and the SDK.
  6. 1.x calls are synchronous and pass documents whole. WASI 0.3 async components are planned for 2.0, behind a host adapter that keeps 1.x plugins running.
These rules are checked automatically:
  • sdk/rust/openidea-plugin/tests/api_frozen.rs compares wit/ with the snapshot of the latest released version in sdk/rust/openidea-plugin/tests/api/released/ (currently 1.4.0). Every released interface, type, function and world must still exist unchanged.
  • crates/ide-plugin/tests/api_compat.rs checks that the versions agree, that the SDK’s WIT copy matches, and that a simulated next-minor host still links every shipped component while another major does not.
  • The release workflow refuses a release whose wit/ version has no snapshot.

​
Older manifests

Manifests in the 0.1 format (openidea-api = "0.1") still load their contributions, but 0.1 code no longer runs. Rebuild against the 1.x SDK.