API: Plugins | Pupitre

This reference is generated before development, checking and building from declarations reachable through the package’s published entry points, following re-exports. Internal source-module exports are omitted. Types shown together share their source module; follow the source link for imports and implementation. Use the guides for examples and runtime behavior.

src/definition/plugin.ts

Source

/** Context handed to `plugin.boot()` once per panel, after resolution and before routes. */
export type PluginBootContext = {
    app: ApplicationService;
    manager: PupitreManager;
    /** Fully resolved panel (plugin contributions included). */
    panel: PanelRuntime;
};

/** Context handed to `plugin.extendResource()`. */
export type PluginResourceContext = {
    /** Panel definition after every plugin's `register()` and contributions were applied. */
    panel: PanelDefinition;
    /** Slug of the parent resource when the resource is registered as nested. */
    parent?: string;
};

/**
 * A Pupitre plugin (WP36). Plugins are plain objects; packages usually export a
 * factory (`shield({ ... })`) returning `definePlugin({ ... })`.
 *
 * Application order per panel, in the order passed to `.plugins([...])`:
 * 1. `register(panel)` — may return a new builder (panel builders are immutable).
 * 2. `resources`, `pages`, `widgets` are appended to the panel's own entries,
 *    `middleware` after the panel middleware, `navigation` to the panel navigation.
 * 3. `extendResource(resource)` runs for every resource of the panel (nested included).
 * 4. `boot({ app, manager, panel })` runs once the panel is resolved, before routes.
 */
export type PupitrePlugin = {
    /** Unique kebab-case identifier, e.g. `shield` or `acme-audit`. */
    readonly name: string;
    catalog?: readonly CatalogExtension[];
    messages?: LocaleMessages;
    register?(panel: PanelBuilder): PanelBuilder | void;
    resources?: readonly unknown[] | Record<string, unknown>;
    pages?: readonly unknown[] | Record<string, unknown>;
    widgets?: readonly unknown[] | Record<string, unknown>;
    middleware?: PanelDefinition['middleware'];
    navigation?: readonly Definable<NavEntryDefinition>[];
    extendResource?(resource: ResourceDefinition<LucidRow>, context: PluginResourceContext): ResourceDefinition<LucidRow> | void;
    boot?(context: PluginBootContext): void | Promise<void>;
};

src/builder/plugin.ts

Source

/**
 * Declares a Pupitre plugin. Validates the shape eagerly so typos surface at
 * import time instead of being silently ignored at boot.
 */
export function definePlugin<Plugin extends PupitrePlugin>(plugin: Plugin): Plugin;