@dxos/app-framework - v0.16.0
    Preparing search index...

    Interface PluginManager

    Interface for the Plugin Manager.

    interface PluginManager {
        "[ManagerTypeId]": typeof PluginManager.ManagerTypeId;
        activation: PubSub<ActivationMessage>;
        active: Atom<readonly string[]>;
        capabilities: CapabilityManager.CapabilityManager;
        core: Atom<readonly string[]>;
        devPluginIds: Atom<readonly string[]>;
        enabled: Atom<readonly string[]>;
        eventsFired: Atom<readonly string[]>;
        failed: Atom<readonly PluginFailure[]>;
        modules: Atom<readonly PluginModule[]>;
        pendingReset: Atom<readonly string[]>;
        pluginRegistry: Registry.Manager;
        plugins: Atom<readonly Plugin.Plugin[]>;
        registry: AtomRegistry;
        activate(
            event: string | ActivationEvent.ActivationEvent,
            params?: { after?: string; before?: string },
        ): Effect<boolean, Error>;
        add(id: string): Effect<Plugin.Plugin, Error>;
        clearFailure(id: string): boolean;
        deactivate(id: string): Effect<boolean, Error>;
        disable(id: string, opts?: { cascade?: boolean }): Effect<boolean, Error>;
        enable(
            id: string,
            opts?: { resolveDependencies?: boolean },
        ): Effect<boolean, Error>;
        getActive(): readonly string[];
        getCore(): readonly string[];
        getDependencies(
            id: string,
            opts?: { transitive?: boolean },
        ): readonly string[];
        getDependents(
            id: string,
            opts?: { enabledOnly?: boolean; transitive?: boolean },
        ): readonly string[];
        getDevPluginIds(): readonly string[];
        getEnabled(): readonly string[];
        getEventsFired(): readonly string[];
        getFailed(): readonly PluginFailure[];
        getModules(): readonly PluginModule[];
        getPendingReset(): readonly string[];
        getPlugins(): readonly Plugin.Plugin[];
        reload(moduleIds: readonly string[]): Effect<boolean, Error>;
        reloadPlugin(id: string): Effect<boolean, Error>;
        remove(id: string, opts?: { cascade?: boolean }): Effect<boolean, Error>;
        reset(
            event: string | ActivationEvent.ActivationEvent,
        ): Effect<boolean, Error>;
        shutdown(): Effect<boolean, Error>;
        start(): Effect<boolean, Error>;
    }
    Index

    Properties

    [ManagerTypeId] activation active capabilities core devPluginIds enabled eventsFired failed modules pendingReset pluginRegistry plugins registry

    Methods

    activate add clearFailure deactivate disable enable getActive getCore getDependencies getDependents getDevPluginIds getEnabled getEventsFired getFailed getModules getPendingReset getPlugins reload reloadPlugin remove reset shutdown start

    Properties

    "[ManagerTypeId]": typeof PluginManager.ManagerTypeId
    activation: PubSub<ActivationMessage>
    active: Atom<readonly string[]>
    capabilities: CapabilityManager.CapabilityManager
    core: Atom<readonly string[]>
    devPluginIds: Atom<readonly string[]>

    Ids of currently-registered plugins that came from a dev source (loaded via LoadedPlugin with dev: true). Subscribers can use this to badge dev-overridden plugins or to derive the id of the active dev plugin for an "uninstall dev plugin" affordance.

    enabled: Atom<readonly string[]>
    eventsFired: Atom<readonly string[]>
    failed: Atom<readonly PluginFailure[]>

    Plugins that failed to load or activate. Subscribers (e.g. the registry UI) can use this to flag unhealthy entries; a plugin id appears here at most once with its most recent failure.

    modules: Atom<readonly PluginModule[]>
    pendingReset: Atom<readonly string[]>
    pluginRegistry: Registry.Manager

    Cached registry catalog state plus pass-throughs for listVersions / getPlugin. Always present — the host supplies a pluginRegistryProvider via ManagerOptions for real backends, or it falls back to a no-op implementation that yields an empty catalog.

    plugins: Atom<readonly Plugin.Plugin[]>
    registry: AtomRegistry

    Methods

    • Loads a plugin via the plugin loader and registers it without enabling it. Returns the loaded plugin so callers can enable it by its canonical id (which may differ from the locator used to load it, e.g. URL loaders). A plugin whose id is already enabled, such as one persisted from an earlier session, is activated as part of the add.

      Parameters

      • id: string

      Returns Effect<Plugin.Plugin, Error>

    • Disables a plugin.

      By default, cascades to currently-enabled dependents (transitively, leaves first) so disabling a depended-upon plugin never leaves its dependents stranded. Pass cascade: false to disable only the named plugin and leave its dependents enabled-but-broken — VS Code-style disable parity for callers that want the escape hatch (e.g. when swapping in an alternative implementation that satisfies the dependents' needs in its own way).

      Fails with Plugin.PluginDependencyError (reason: 'core-dependent') when cascading would require disabling a core plugin; UI flows should surface their own confirmation before calling disable with the default.

      Parameters

      • id: string
      • Optionalopts: { cascade?: boolean }

      Returns Effect<boolean, Error>

    • Enables a plugin.

      Default behavior auto-resolves the plugin's declared dependsOn closure: missing entries that exist in the plugin registry catalog are installed via add, then enabled in dependency-first order. Set resolveDependencies to false to enable only the named plugin and skip the closure walk entirely — useful when substituting an alternative plugin that satisfies the dependent's capability needs in its own way.

      Parameters

      • id: string
      • Optionalopts: { resolveDependencies?: boolean }

      Returns Effect<boolean, Error>

    • Returns the plugin ids that the given plugin declares as dependencies.

      Walks meta.dependsOn from both registered plugins and the plugin registry catalog so callers can preview the closure for a plugin that isn't yet installed. With transitive: true (default), returns the full dependency closure in dependency-first order (deps before dependents). Without it, returns the direct declarations only.

      Parameters

      • id: string
      • Optionalopts: { transitive?: boolean }

      Returns readonly string[]

    • Returns the plugin ids that declare the given plugin as a dependency.

      Walks meta.dependsOn over registered plugins. With transitive: true (default), returns the full reverse closure. With enabledOnly: true, filters to currently-enabled dependents — used by UI flows to preview what a cascading disable would touch.

      Parameters

      • id: string
      • Optionalopts: { enabledOnly?: boolean; transitive?: boolean }

      Returns readonly string[]

    • Re-runs the given active modules in place: deactivates them and every active module that transitively requires a singleton capability they provide, then activates that set again. Hot module replacement calls this after swapping a module's body; inactive ids are ignored.

      Parameters

      • moduleIds: readonly string[]

      Returns Effect<boolean, Error>

      Whether any module was reloaded and every re-activation succeeded.

    • Re-creates a lazy plugin from its loader, with the options it was made with, and swaps it in place: if enabled, its modules and their singleton dependents are torn down and the new plugin's modules activate for every event that already fired. Hot module replacement calls this when the plugin's definition changes.

      Parameters

      • id: string

      Returns Effect<boolean, Error>

      Whether a resolved plugin was replaced (and, if enabled, re-enabled).

    • Shuts down the manager by deactivating all active modules in reverse activation order, clearing all capabilities, and resetting lifecycle bookkeeping. Plugins, core, enabled, and modules remain intact so the manager can be reused.

      Returns Effect<boolean, Error>

    • Runs startup: the capability-dependency resolution pass for dependency-mode modules, concurrently with the event-mode activation pass for any module explicitly targeting the Startup event. The event-level Startup activated message publishes only after both passes complete. Idempotent — subsequent calls activate whatever registered since. activate(Startup) delegates here.

      Returns Effect<boolean, Error>

    Settings

    Member Visibility

    On This Page

    Properties
    Methods