Skip to main content
PluginRegistry is the central coordinator for your plugin’s runtime. You interact with it to register message handlers, access key-value stores, configure storage and capabilities, and retrieve diagnostics. All methods are static.
You do not call registerPlugin yourself — the FDO_SDK constructor does this automatically when you instantiate your plugin class.

​
Constants

​
DIAGNOSTICS_HANDLER

public static readonly DIAGNOSTICS_HANDLER = "__sdk.getDiagnostics"
The reserved handler name the SDK registers internally for host-initiated diagnostics requests. Do not register a handler under this name.

​
Plugin registration

​
registerPlugin()

public static registerPlugin(plugin: FDO_SDK): void
Registers a plugin instance as the active plugin. Called automatically by the FDO_SDK constructor — you do not call this directly.
​
plugin
FDO_SDK
required
The plugin instance to register. Only one plugin instance is active at a time.

​
Handler registration

​
registerHandler()

public static registerHandler(name: string, handler: PluginHandler): void
Registers a named message handler. The FDO host dispatches UI_MESSAGE events to your plugin by handler name.
​
name
string
required
A unique handler name. Use dot-separated namespacing to avoid collisions (e.g., "my-plugin.action.run").
​
handler
PluginHandler
required
A function that receives the message payload and returns a result or a Promise of a result. See the PluginHandler type.
PluginRegistry.registerHandler("my-plugin.greet", async (data) => {
  const { name } = data as { name: string };
  return { message: `Hello, ${name}!` };
});
Register all handlers inside your init() method so they are available before the host sends any messages.

​
clearHandler()

public static clearHandler(name: string): void
Removes a previously registered handler by name. Has no effect if the handler does not exist.
​
name
string
required
The name of the handler to remove.
PluginRegistry.clearHandler("my-plugin.greet");

​
clearAllHandlers()

public static clearAllHandlers(): void
Removes all registered handlers. Use this when you need to fully reset handler state. 
PluginRegistry.clearAllHandlers();

​
Store access

​
useStore()

public static useStore(name?: string): StoreType
Returns a scoped store instance by name. If the named store is not registered, falls back to "default" with a warning.
​
name
string
default:"\"default\""
The store name. Built-in options are "default" (in-memory) and "json" (persistent, file-backed).
Returns: StoreType — a scoped key-value store instance.
The "json" store requires the storage.json capability to be granted and a configured storage root. Using it without these throws an error.
// In-memory store (default)
const store = PluginRegistry.useStore();
store.set("last-run", new Date().toISOString());

// Persistent JSON store
const jsonStore = PluginRegistry.useStore("json");
jsonStore.set("user-preference", "dark");
const pref = jsonStore.get<string>("user-preference");

​
StoreType interface

All store instances expose the following methods: 
get<T = unknown>(key: string): T | undefined
Retrieves the value stored under key, typed as T. Returns undefined if the key does not exist.
const value = store.get<string>("my-key");

set<T = unknown>(key: string, value: T): void
Stores value under key. Overwrites any existing value.
store.set("count", 42);

remove(key: string): void
Deletes the entry for key. Has no effect if the key does not exist.
store.remove("session-token");

clear(): void
Removes all entries from the store scope.
store.clear();

has(key: string): boolean
Returns true if key exists in the store.
if (store.has("initialized")) {
  // skip first-run setup
}

keys(): string[]
Returns all keys currently in the store scope.
const allKeys = store.keys();

​
registerStore()

public static registerStore(name: string, storeRegistration: StoreRegistration): void
Registers a custom store factory or store instance under a given name. The name must not conflict with an already-registered store.
​
name
string
required
A unique name for the store. Must not already be registered.
​
storeRegistration
StoreRegistration
required
Either a StoreType instance or a StoreFactory function (context: StoreFactoryContext) => StoreType.
import { PluginRegistry } from "@anikitenko/fdo-sdk";
import type { StoreType } from "@anikitenko/fdo-sdk";

const myStore: StoreType = {
  get: (key) => myBackend.get(key),
  set: (key, value) => myBackend.set(key, value),
  remove: (key) => myBackend.delete(key),
  clear: () => myBackend.clear(),
  has: (key) => myBackend.has(key),
  keys: () => myBackend.keys(),
};

PluginRegistry.registerStore("my-backend", myStore);

​
clearAllStoreInstances()

public static clearAllStoreInstances(): void
Disposes and removes all active store instances across all plugin scopes. Calls flush() and dispose() on each store if they implement those lifecycle hooks. Primarily used in tests. 
PluginRegistry.clearAllStoreInstances();

​
Storage configuration

​
configureStorage()

public static configureStorage(configuration: StorageConfiguration): void
Sets the storage root directory used by the "json" persistent store. You can also set the FDO_SDK_STORAGE_ROOT environment variable instead.
​
configuration
StorageConfiguration
required
PluginRegistry.configureStorage({
  rootDir: "/var/lib/fdo-plugins",
});

​
Capability configuration

​
configureCapabilities()

public static configureCapabilities(configuration: CapabilityConfiguration): void
Grants capabilities to the plugin at runtime. The FDO host typically calls this during PLUGIN_INIT — you call it directly only in tests or host adapter code.
​
configuration
CapabilityConfiguration
required
PluginRegistry.configureCapabilities({
  granted: ["storage.json", "system.process.exec"],
});

​
UI configuration

​
getQuickActions()

public static getQuickActions(): QuickAction[]
Returns the quick actions defined by the plugin via the QuickActionMixin. Returns an empty array if the plugin does not define quick actions. Returns: QuickAction[] 
const actions = PluginRegistry.getQuickActions();

​
getSidePanelConfig()

public static getSidePanelConfig(): SidePanelConfig | null
Returns the side panel configuration defined by the plugin via the SidePanelMixin, or null if not configured. Returns: SidePanelConfig | null 
const panel = PluginRegistry.getSidePanelConfig();

​
Host-facing lifecycle methods

These methods are called by the FDO host. You do not call them from plugin code.

​
callInit()

public static callInit(): void
Invokes the registered plugin’s init() method. Increments the internal init counter and emits lifecycle events. Throws if init() throws.

​
callRenderer()

public static callRenderer(): SerializedRenderPayload | NullableSerializedRenderPayload
Invokes the registered plugin’s serializeRender() and serializeRenderOnLoad() methods and returns the combined payload. Returns { render: undefined, onLoad: undefined } if no plugin is registered. Returns:
​
render
string | undefined
required
JSON-serialized output of render().
​
onLoad
string | undefined
required
JSON-serialized output of renderOnLoad().

​
callHandler()

public static async callHandler(name: string, data: unknown): Promise<unknown>
Invokes the named handler with the provided data. Returns null if the handler does not exist or if the handler throws.
​
name
string
required
The handler name to invoke.
​
data
unknown
required
The payload to pass to the handler.
Returns: Promise<unknown> — the handler’s return value, or null on error or if not found.

​
assertHostApiCompatibility()

public static assertHostApiCompatibility(hostApiVersion?: string): void
Validates that the host’s API major version matches the SDK’s API_VERSION. Throws if the major versions differ. If hostApiVersion is undefined, this is a no-op.
​
hostApiVersion
string
The API version string provided by the host, e.g. "1.0.0". Must follow major.minor.patch format.
PluginRegistry.assertHostApiCompatibility("1.2.0"); // passes — major matches
PluginRegistry.assertHostApiCompatibility("2.0.0"); // throws — major mismatch

​
Diagnostics

​
getDiagnostics()

public static getDiagnostics(request?: PluginDiagnosticsRequest): PluginDiagnostics
Returns a structured snapshot of the plugin’s current health, capability state, registered handlers and stores, and recent notifications.
​
request
PluginDiagnosticsRequest
Returns: PluginDiagnostics — a structured object with the following shape:
​
apiVersion
string
The SDK API version at the time of the diagnostic snapshot.
​
pluginId
string
The scoped identifier derived from plugin metadata.
​
metadata
PluginMetadata | null
The plugin’s registered metadata, or null if metadata is unavailable.
​
health
object
​
capabilities
object
​
notifications
object
const diagnostics = PluginRegistry.getDiagnostics({ notificationsLimit: 10 });
console.log(diagnostics.health.status); // "healthy" or "degraded"

​
Utility

​
getPluginScopeForLogging()

public static getPluginScopeForLogging(plugin?: FDO_SDK | null): string
Returns the logging scope identifier for the given plugin instance, derived from its metadata. Returns "anonymous-plugin" if metadata is unavailable.
​
plugin
FDO_SDK | null
The plugin instance to resolve a scope for. Defaults to the currently registered plugin if omitted.
Returns: string — the plugin’s scoped identifier used in log context.

​
clearPlugin()

public static clearPlugin(): void
Deregisters the current plugin instance, disposes its store scope, and resets diagnostics state. Primarily used in tests. 
PluginRegistry.clearPlugin();