Another plugin’s INSTANCE: whether it is there, waiting for it, and asking the user to bring it in.
This is the path for a plugin that publishes nothing through the library’s registry, which is most of them. A provider that does publish is better reached through watchPluginApi (./plugin-api.ts): its reference is live, version-negotiated and revoked when the provider goes away, none of which a bare instance offers. And a plugin that must STOP running when another one goes away declares it through PluginBase.getPluginDependencies(), whose gate owns that teardown — requirePlugin is a one-shot wait, not a second dependency system.
What “loaded” can and cannot mean, read from Obsidian 1.15.1:
Plugins.loadPlugin stores the instance in app.plugins.plugins BEFORE it awaits plugin.load(), and Plugin.load sets _loaded before it awaits onload(). So app.plugins.getPlugin(id) can return a plugin whose onload is still running, and _loaded cannot tell the two apart. Plugins.enablePlugin brackets the load with loadingPluginId, which is the one signal that does, so an instance whose id is loadingPluginId reads as PluginAvailability.Loading. - onload having settled is the most anything can promise. A plugin that starts further work from onload without awaiting it, or waits for layout-ready, is “loaded” before that work is done, and Obsidian has no hook saying every plugin has finished initializing. A plugin built on this library says more through the obsidian-lib:plugin-loaded broadcast, which follows its published APIs. - app.plugins is an Events source that triggers changed, debounced by one macrotask, after every enable, disable, install, uninstall and manifest reload. That is what a wait subscribes to, so nothing here polls. It fires after enablePlugin returned, when loadingPluginId is null again.
A type argument alone is a caller’s ASSERTION about the instance, not a check: nothing at runtime knows what TPlugin is. Pass isPlugin to have the shape verified; an instance failing it reads as PluginAvailability.ShapeMismatch, the usual sign of a release that renamed what the caller uses.
| Function |
Description |
| getLoadedPlugin |
Returns another plugin’s instance when it is PluginAvailability.Available, and null otherwise. Unlike app.plugins.getPlugin, it never returns an instance whose onload is still running. |
| getPluginAvailability |
Reads whether another plugin’s instance can be used right now, and if not, why. |
| requirePlugin |
Waits for another plugin to become PluginAvailability.Available, asking the user to repair it while it is not. Resolves at once when it already is. Otherwise, once the workspace layout is ready — before that, a plugin Obsidian has not loaded yet is indistinguishable from a missing one — a notice says what is wrong and offers the matching repair: install, enable, or update, plus a way to the community plugins list. The notice follows the state as it changes and goes away when the wait settles. A repair that fails is reported and leaves the wait running, so the user can try again or fix it by hand. The promise settles ONCE. It does not watch the plugin afterwards: a consumer that must stop when the plugin goes away declares a dependency through PluginBase.getPluginDependencies() instead. |
| waitForPlugin |
Waits for another plugin to become PluginAvailability.Available. Resolves at once when it already is, which covers a consumer reloaded after its dependency. Otherwise it re-reads the state on every app.plugins changed and every obsidian-lib:plugin-loaded broadcast, so a plugin enabled, updated or reloaded later is picked up with no polling. It subscribes before its first read, so a change landing in between cannot be missed. Every listener and timer is removed when it settles. |
| Enum |
Description |
| PluginAvailability |
Whether another plugin’s instance can be used right now, and if not, why. |
| Variable |
Description |
| PLUGINS_CHANGED_EVENT_NAME |
The event app.plugins triggers after every enable, disable, install, uninstall and manifest reload. Read from Obsidian 1.15.1: didChange triggers it debounced by one macrotask, so several changes in one task arrive as one event, after enablePlugin / disablePlugin returned. |