Plugin API
Plugin-author declarations, manifests, permissions, capabilities, phases, stores, and compatibility helpers.
Plugin API exports
46 public exports, grouped under their canonical import boundary.
@tavojs/core/plugin
Canonical import boundary for every symbol in this section.
AnyPluginToken#
type AnyPluginToken = PluginCapabilityToken<any, any> | PluginStoreToken<any>;Defines the any plugin token contract used by the Plugin API v1.
Related guidecheckPluginCompatibility#
checkPluginCompatibility(plugin: { id: string; apiVersion: number; }): { compatible: boolean; currentVersion: 1; requestedVersion: number; diagnostic?: PluginDiagnostic | undefined; }Checks a plugin descriptor without running phase code.
Related guidedefineCapability#
defineCapability<T, TScope extends "runtime" | "request">(definition: { provider: string; name: string; scope: TScope; }): PluginCapabilityToken<T, TScope>Defines and type-checks capability for the Plugin API v1.
Related guidedefinePlugin#
definePlugin<T extends TavoPlugin>(plugin: T): TDefines a Plugin API v1 descriptor. Validation occurs during graph compilation.
Related guidedefinePluginFactory#
definePluginFactory<TOptions, TPlugin extends TavoPlugin>(factory: (options: TOptions) => TPlugin): (options: TOptions) => TPluginDefines a typed plugin factory.
Related guidedefinePluginPhase#
definePluginPhase<T extends TavoPluginPhase>(phase: T): TDefines a phase implementation while preserving its literal keys.
Related guidedefinePluginStore#
definePluginStore<T extends AnyRecord>(definition: Omit<PluginStoreToken<T>, "hydrate" | "kind" | "scope"> & { hydrate?: boolean | undefined; }): PluginStoreToken<T>Defines an owned runtime store and its optional hydration contract.
Related guideMaybePromise#
type MaybePromise<T> = T | Promise<T>;Defines the maybe promise contract used by the Plugin API v1.
Related guidePluginBuildDeclaration#
type PluginBuildDeclaration = {
aliases?: Readonly<Record<string, string>>;
defines?: Readonly<Record<string, string>>;
plugins?: readonly PluginBuildItemDeclaration[];
};Defines the plugin build declaration contract used by the Plugin API v1.
Related guidePluginBuildItemDeclaration#
type PluginBuildItemDeclaration = {
id: string;
before?: readonly string[];
after?: readonly string[];
};Defines the plugin build item declaration contract used by the Plugin API v1.
Related guidePluginCapabilityResolver#
type PluginCapabilityResolver = {
resolve<T>(token: PluginCapabilityToken<T, "runtime"> | PluginStoreToken<any>): T;
tryResolve<T>(token: PluginCapabilityToken<T, "runtime"> | PluginStoreToken<any>): T | undefined;
};Defines the plugin capability resolver contract used by the Plugin API v1.
Related guidePluginCapabilityToken#
type PluginCapabilityToken<T = unknown, TScope extends PluginScope = PluginScope> = {
readonly kind: "capability";
readonly provider: string;
readonly name: string;
readonly scope: TScope;
readonly __tavoCapabilityType?: T;
};Defines the plugin capability token contract used by the Plugin API v1.
Related guidePluginDependency#
type PluginDependency = {
id: string;
instanceId?: string;
version: string;
optional?: boolean;
capabilities?: readonly AnyPluginToken[];
};Defines the plugin dependency contract used by the Plugin API v1.
Related guidePluginDiagnostic#
type PluginDiagnostic = {
code: PluginDiagnosticCode;
severity: "error" | "warning";
phase: "compile" | "initialize" | "build" | "request" | "dispose";
message: string;
resource?: string;
owners?: readonly string[];
hint?: string;
};Defines the plugin diagnostic contract used by the Plugin API v1.
Related guidePluginDiagnosticCode#
type PluginDiagnosticCode = "TAVO_PLUGIN_001" | "TAVO_PLUGIN_002" | "TAVO_PLUGIN_003" | "TAVO_PLUGIN_004" | "TAVO_PLUGIN_005" | "TAVO_PLUGIN_006" | "TAVO_PLUGIN_007" | "TAVO_PLUGIN_008" | "TAVO_PLUGIN_009";Defines the plugin diagnostic code contract used by the Plugin API v1.
Related guidePluginEndpointDeclaration#
type PluginEndpointDeclaration = {
id: string;
methods: readonly string[];
match: PluginEndpointMatcher;
validateOrigin?: boolean;
};Defines the plugin endpoint declaration contract used by the Plugin API v1.
Related guidePluginEndpointMatcher#
type PluginEndpointMatcher = {
kind: "exact";
path: string;
} | {
kind: "subtree";
path: string;
};Defines the plugin endpoint matcher contract used by the Plugin API v1.
Related guidePluginExposureDeclaration#
type PluginExposureDeclaration = {
target: "page" | "server";
from?: string;
to: string;
reason: string;
};Defines the plugin exposure declaration contract used by the Plugin API v1.
Related guidePluginExposureTarget#
type PluginExposureTarget = string | {
from?: string;
to: string;
};Defines the plugin exposure target contract used by the Plugin API v1.
Related guidePluginHeadDeclaration#
type PluginHeadDeclaration = {
id: string;
key: string;
cardinality: "singleton" | "multi";
unsafeHeadHtml?: boolean;
};Defines the plugin head declaration contract used by the Plugin API v1.
Related guidePluginHeadImplementation#
type PluginHeadImplementation = Child | string | ((context: PluginResolveContext) => MaybePromise<Child | string>);Defines the plugin head implementation contract used by the Plugin API v1.
Related guidePluginMiddlewareDeclaration#
type PluginMiddlewareDeclaration = {
id: string;
target: PluginMiddlewareTarget;
stage: PluginMiddlewareStage;
before?: readonly string[];
after?: readonly string[];
};Defines the plugin middleware declaration contract used by the Plugin API v1.
Related guidePluginMiddlewareStage#
type PluginMiddlewareStage = "server:before-handler" | "page:before-app" | "page:after-app";Defines the plugin middleware stage contract used by the Plugin API v1.
Related guidePluginMiddlewareTarget#
type PluginMiddlewareTarget = "server" | "page";Defines the plugin middleware target contract used by the Plugin API v1.
Related guidePluginOverride#
type PluginOverride = {
kind: "page" | "endpoint" | "head" | "alias" | "define";
key: string;
replace: {
plugin: string;
instanceId?: string;
};
with: {
owner: "app" | string;
instanceId?: string;
key?: string;
};
};Defines the plugin override contract used by the Plugin API v1.
Related guidePluginPageDeclaration#
type PluginPageDeclaration = {
id: string;
path: string;
};Defines the plugin page declaration contract used by the Plugin API v1.
Related guidePluginPermissionDeclaration#
type PluginPermissionDeclaration = {
name: "unsafeHeadHtml";
/** Required permissions are part of the plugin's installation contract. */
required?: boolean;
reason: string;
};Defines the plugin permission declaration contract used by the Plugin API v1.
Related guidePluginPhaseLoader#
type PluginPhaseLoader = () => MaybePromise<TavoPluginPhase | {
default: TavoPluginPhase;
}>;Defines the plugin phase loader contract used by the Plugin API v1.
Related guidePluginPhaseTarget#
type PluginPhaseTarget = "client" | "server" | "build";Defines the plugin phase target contract used by the Plugin API v1.
Related guidePluginRequestResolveContext#
type PluginRequestResolveContext = Omit<PluginResolveContext, "resolve" | "tryResolve"> & {
readonly request: Request;
resolve<T>(token: PluginCapabilityToken<T, any> | PluginStoreToken<any>): Promise<T>;
tryResolve<T>(token: PluginCapabilityToken<T, any> | PluginStoreToken<any>): Promise<T | undefined>;
};Provides the context passed to plugin request resolve in the Plugin API v1.
Related guidePluginRequestResourceFactory#
type PluginRequestResourceFactory<T = unknown> = (context: PluginRequestResolveContext) => MaybePromise<T>;Defines the plugin request resource factory contract used by the Plugin API v1.
Related guidePluginResolveContext#
type PluginResolveContext = {
readonly instanceId: string;
resolve<T>(token: PluginCapabilityToken<T, "runtime"> | PluginStoreToken<any>): T;
tryResolve<T>(token: PluginCapabilityToken<T, "runtime"> | PluginStoreToken<any>): T | undefined;
};Provides the context passed to plugin resolve in the Plugin API v1.
Related guidePluginResourceFactory#
type PluginResourceFactory<T = unknown> = (context: PluginResolveContext) => MaybePromise<T>;Defines the plugin resource factory contract used by the Plugin API v1.
Related guidePluginScope#
type PluginScope = "runtime" | "request";Defines the plugin scope contract used by the Plugin API v1.
Related guidePluginServerHandler#
type PluginServerHandler = (context: PluginServerHandlerContext) => MaybePromise<Response>;Defines the plugin server handler contract used by the Plugin API v1.
Related guidePluginServerHandlerContext#
type PluginServerHandlerContext = PluginRequestResolveContext & {
params: Record<string, string>;
};Provides the context passed to plugin server handler in the Plugin API v1.
Related guidePluginServerMiddleware#
type PluginServerMiddleware = (context: PluginServerHandlerContext) => MaybePromise<Response | void>;Defines the plugin server middleware contract used by the Plugin API v1.
Related guidePluginStoreFactory#
type PluginStoreFactory<T extends AnyRecord = AnyRecord> = (context: PluginResolveContext) => MaybePromise<T | Store<T>>;Defines the plugin store factory contract used by the Plugin API v1.
Related guidePluginStoreToken#
type PluginStoreToken<T extends AnyRecord = AnyRecord> = {
readonly kind: "store";
readonly provider: string;
readonly name: string;
readonly scope: "runtime";
readonly hydrate: boolean;
readonly validate?: (value: unknown) => value is T;
readonly serialize?: (value: T) => unknown;
readonly deserialize?: (value: unknown) => T;
readonly __tavoStoreType?: T;
};Defines the plugin store token contract used by the Plugin API v1.
Related guidePluginUse#
type PluginUse = TavoPlugin | (PluginInstallation & {
/** Remaps this installation's manifest-declared public exposure. */
expose?: {
page?: PluginExposureTarget;
server?: PluginExposureTarget;
};
});Application-owned ergonomic installation record.
Related guidePluginUseConfiguration#
type PluginUseConfiguration = {
use: readonly PluginUse[];
overrides?: readonly PluginOverride[];
};Defines the plugin use configuration contract used by the Plugin API v1.
Related guideTAVO_PLUGIN_API_VERSION#
TAVO_PLUGIN_API_VERSION: 1Current public contract implemented by the Tavo.js plugin runtime.
Related guideTavoPlugin#
type TavoPlugin = {
id: string;
version: string;
apiVersion: typeof TAVO_PLUGIN_API_VERSION;
manifest: TavoPluginManifest;
client?: PluginPhaseLoader;
server?: PluginPhaseLoader;
build?: PluginPhaseLoader;
};Defines the tavo plugin contract used by the Plugin API v1.
Related guideTavoPluginInput#
type TavoPluginInput = PluginUseConfiguration | readonly PluginUse[];Author input; normalized to the compiler's internal graph configuration.
Related guideTavoPluginManifest#
type TavoPluginManifest = {
provides?: readonly AnyPluginToken[];
dependencies?: readonly PluginDependency[];
stores?: readonly PluginStoreToken<any>[];
pages?: readonly PluginPageDeclaration[];
endpoints?: readonly PluginEndpointDeclaration[];
middleware?: readonly PluginMiddlewareDeclaration[];
head?: readonly PluginHeadDeclaration[];
build?: PluginBuildDeclaration;
/** Framework permissions enabled by installing this trusted plugin. */
permissions?: readonly PluginPermissionDeclaration[];
/** Default public mounts enabled by installing this trusted plugin. */
exposure?: readonly PluginExposureDeclaration[];
};Defines the tavo plugin manifest contract used by the Plugin API v1.
Related guideTavoPluginPhase#
type TavoPluginPhase = {
capabilities?: Readonly<Record<string, PluginResourceFactory | PluginRequestResourceFactory>>;
stores?: Readonly<Record<string, PluginStoreFactory>>;
pages?: Readonly<Record<string, PageModule>>;
endpoints?: Readonly<Record<string, PluginServerHandler>>;
middleware?: Readonly<Record<string, PageMiddleware | PluginServerMiddleware>>;
head?: Readonly<Record<string, PluginHeadImplementation>>;
build?: {
plugins?: Readonly<Record<string, unknown>>;
};
setup?: (context: PluginResolveContext) => MaybePromise<void>;
dispose?: () => MaybePromise<void>;
};Defines the tavo plugin phase contract used by the Plugin API v1.
Related guide