Skip to content

plugin/third-party-plugin

Typed access to the API of a THIRD-PARTY plugin: one that publishes nothing through this library’s registry.

A plugin built on this library publishes a versioned contract (getPluginApis()), and a consumer reaches it through watchPluginApi (./plugin-api.ts). Most plugins a consumer wants to talk to — Dataview, Templater, Notebook Navigator — are not built on it, so their API hangs off the plugin instance under a name of their own choosing, and every consumer used to reach it by hand through app.plugins with a cast.

A ThirdPartyPluginAdapter says ONCE, for one plugin, how to get from its instance to its typed API, and VERIFIES the shape on the way, so a release that renamed what the adapter reads is “not there” rather than a Cannot read properties of undefined from inside a callback. Everything else here is generic:

  • getThirdPartyPluginApi answers “now”, for a one-shot use. - watchThirdPartyPluginApi answers “now” for as long as a component lives: its ref re-reads on every app.plugins changed and every obsidian-lib:plugin-loaded / -unloaded broadcast, so an OPTIONAL dependency is a ref whose value is null while the plugin is absent, and becomes the API the moment it is enabled. - waitForThirdPartyPluginApi and requireThirdPartyPluginApi are the one-shot waits, built on waitForPlugin / requirePlugin (./plugin-instance.ts), so they share that module’s availability classification, its notice and its repair buttons. - A REQUIRED dependency is declared through PluginBase.getPluginDependencies() as a ThirdPartyPluginDependency (built by createThirdPartyPluginDependency), and the plugin gate keeps onloadImpl from running while it is missing, too old or the wrong shape — the same treatment an own-plugin dependency gets.

Availability is PluginAvailability, read from Obsidian 1.15.1 as plugin-instance.ts documents: an instance whose onload is still running reads as loading, never as available. An adapter’s getApi returning null reads as PluginAvailability.ShapeMismatch.

Interface Description
CreateThirdPartyPluginDependencyParams Parameters for createThirdPartyPluginDependency.
GetThirdPartyPluginApiParams Parameters for getThirdPartyPluginApi and getThirdPartyPluginAvailability.
RequireThirdPartyPluginApiParams Parameters for requireThirdPartyPluginApi.
ThirdPartyPluginAdapter How to get from one third-party plugin’s instance to its typed API. An adapter is plain data plus one function, so it can be a module-level constant shared by every consumer, and adding a plugin means adding one adapter.
ThirdPartyPluginApiRef A live reference to a third-party plugin’s API.
ThirdPartyPluginApiRefEventMap The events a ThirdPartyPluginApiRef fires.
ThirdPartyPluginDependency A third-party plugin another plugin cannot work without, declared through PluginBase.getPluginDependencies(). Built by createThirdPartyPluginDependency, which copies the adapter’s id and name.
WaitForThirdPartyPluginApiParams Parameters for waitForThirdPartyPluginApi.
WatchThirdPartyPluginApiParams Parameters for watchThirdPartyPluginApi.
Function Description
createThirdPartyPluginDependency Builds the declaration of a required third-party plugin, for PluginBase.getPluginDependencies().
getThirdPartyPluginApi Returns a third-party plugin’s typed API when the plugin is PluginAvailability.Available, and null otherwise.
getThirdPartyPluginAvailability Reads whether a third-party plugin’s API can be used right now, and if not, why.
isThirdPartyPluginDependency Checks whether a dependency declared through PluginBase.getPluginDependencies() is a third-party one.
requireThirdPartyPluginApi Waits for a third-party plugin’s API, asking the user to install, enable or update the plugin while it is not available. Settles once; see requirePlugin.
waitForThirdPartyPluginApi Waits for a third-party plugin’s API to become available. Settles once; see waitForPlugin.
watchThirdPartyPluginApi Watches a third-party plugin’s API and returns a live ThirdPartyPluginApiRef. The ref re-reads on every app.plugins changed and every library lifecycle broadcast, so it follows the plugin through enable, disable, update and reload with no polling. This is the shape of an OPTIONAL dependency: read ref.value where the integration is used, and treat null as “not there”.
Type Description
GetThirdPartyPluginAvailabilityParams Parameters for getThirdPartyPluginAvailability.