Core · Package reference

@wrnexus/plugin

Plugin contracts, lifecycle hooks, composition, and framework integration.

v0.8.8Private registryCore

Install the package

After WorkRoot approves private registry access, install the release-aligned package:

bun add @wrnexus/plugin@0.8.8

Request preview access. Never put registry tokens in source control.

Least-privilege package permissions

Package manifests declare every framework capability they register:

{
  "wrnexus": {
    "permissions": ["routes", "migrations"],
    "routes": [{ "kind": "api", "path": "/api/example", "entry": "./route.ts" }]
  }
}

Applications can enable fail-closed grants:

export default {
  pluginPermissions: {
    enforce: true,
    grants: { "example-plugin": ["routes"] },
  },
};

Discovery rejects used-but-undeclared capabilities with WRN-PLUGIN-PERMISSION-UNDECLARED and ungranted capabilities with WRN-PLUGIN-PERMISSION-DENIED. Permissions cover components, browser runtime, assets, styles, routes, middleware, migrations, config, transforms, diagnostics/tooling, and server/build hooks.

Compatibility matrices

Manifests can add compatibility: { bunMin: "1.3.0", os: ["linux", "darwin"] } alongside runtimes and requires. Use testPluginCompatibility(manifest, targets) in a package test to exercise the complete support matrix. Runtime discovery enforces the same Bun minimum, OS, runtime, and capability declarations used by the test kit.

Deterministic WRNexusJS plugin contracts for configuration, AST/code transforms, diagnostics, development servers, production builds, and DevToolbar extensions.

Use definePlugin() and declare enforce, before, or after when ordering matters. Duplicate names and dependency cycles are rejected.

Complete lifecycle and contributions

Plugins may implement setup, configure, configResolved, transformAst, transformCode, diagnostics, routes, configureServer, buildStart, buildEnd, render, deploy, shutdown, and hmrUpdate. The runner preserves resolved plugin order for every hook and executes setup exactly once.

In addition to components, routes, middleware, assets, styles, runtimes, and migrations, plugins can contribute directives, cliCommands, virtualModules, deploymentAdapters, configSchemas, documentation, and typeDefinitions. Names are collision checked. Configuration schemas run after configuration resolution, CLI commands are callable as normal wrnexus commands, directives participate in AST transformation, and production builds materialize virtual modules and invoke matching contributed adapters.

Complete TypeScript API

Generated from the exact installed package declarations.

export { PageAst, WrnDiagnostic } from '@wrnexus/syntax';
import { WrnexusPackageManifest, WrnexusPlugin, PluginInput, PluginContext, PluginRunner } from './types.js';
export { ClientRuntimeDefinition, ClientRuntimeInject, ClientRuntimeLoad, ClientRuntimeType, PackageAssetDefinition, PackageMigrationDefinition, PackagePluginManifest, PackageRouteDefinition, PackageStyleDefinition, PluginCliCommand, PluginCommand, PluginConfigSchema, PluginContributions, PluginDeploymentAdapter, PluginDevToolbarPanel, PluginDirective, PluginOrder, PluginPermission, PluginVirtualModule, TransformContext } from './types.js';
export { assertContributionId, contentTypeForPath, defaultClientRuntimePath, defaultPackageAssetPath, definePackageManifest, normalizeClientRuntime, normalizePackageAsset, validateStyleIds } from './manifest.js';
export { DiscoverPluginOptions, discoverPlugins } from './discovery.js';

interface PluginCompatibilityTarget {
    runtime: "bun" | "node" | "edge" | "worker" | "service-worker" | "browser";
    version?: string;
    os?: "win32" | "linux" | "darwin" | string;
    capabilities?: readonly string[];
}
interface PluginCompatibilityResult {
    target: PluginCompatibilityTarget;
    ok: boolean;
    issues: Array<{
        code: "WRN-PLUGIN-MATRIX-RUNTIME" | "WRN-PLUGIN-MATRIX-VERSION" | "WRN-PLUGIN-MATRIX-OS" | "WRN-PLUGIN-MATRIX-CAPABILITY";
        message: string;
    }>;
}
declare function testPluginCompatibility(manifest: WrnexusPackageManifest, targets: readonly PluginCompatibilityTarget[]): PluginCompatibilityResult[];

declare function definePlugin(plugin: WrnexusPlugin): WrnexusPlugin;
declare function flattenPlugins(input: PluginInput, output?: WrnexusPlugin[]): WrnexusPlugin[];

/** Resolve plugin order deterministically and reject duplicates/cycles. */
declare function resolvePlugins(input: PluginInput): WrnexusPlugin[];
declare function createPluginRunner(input: PluginInput, context: PluginContext): PluginRunner;

export { type PluginCompatibilityResult, type PluginCompatibilityTarget, PluginContext, PluginInput, PluginRunner, WrnexusPackageManifest, WrnexusPlugin, createPluginRunner, definePlugin, flattenPlugins, resolvePlugins, testPluginCompatibility };

Examples

Copy-ready examples from the installed package documentation.

Package manifests declare every framework capability they register

{
  "wrnexus": {
    "permissions": ["routes", "migrations"],
    "routes": [{ "kind": "api", "path": "/api/example", "entry": "./route.ts" }]
  }
}

Applications can enable fail-closed grants

export default {
  pluginPermissions: {
    enforce: true,
    grants: { "example-plugin": ["routes"] },
  },
};