Plugins

@veap/plugins provides plugin contracts and lifecycle, registry and persistence utilities, navigation metadata, React extension points, and route-tree integration. The package depends on several Veap capabilities; install its declared dependencies and peer dependencies as appropriate for the features you use.

Guides#

• Plugin contract
• Lifecycle
• Dependencies and metadata
• Routes and UI extensions
• Build and validate a plugin

Plugins are executable code, not sandboxed extensions. Only load code you trust, and treat every plugin's migrations, server handlers, hooks, and UI components as part of your application's security boundary.

Overview#

@veap/plugins supplies plugin contracts, a registry, persistence, migration integration, navigation definitions, React extension points/widgets, and virtual routing infrastructure. Its public export map defines these supported subpaths: ., ./client, ./router, ./models, ./actions, ./server, and ./migrations.

Plugin contract#

The source IPlugin contract supports a manifest, optional migrations, lifecycle callbacks (init, onMigrate, onEnable, onDisable), hooks, extensions, widgets, navigation, nested plugins, locales, and an optional routeTree. PluginManifest includes an ID, name, version, optional description/dependencies/extension targets/enabled/system/setup flags and author. A Zod PluginManifestSchema is exported in the common types module.

The package can build a manifest from a package.json using createManifestFromPackageJson(pkg). It reads pkg.veap metadata and falls back to the package name/version/description. The documented package metadata replaces a standalone manifest.json for this helper.

import type { IPlugin } from "@veap/plugins";

export const ExamplePlugin: IPlugin = {
  manifest: {
    id: "example-analytics",
    name: "Example Analytics",
    version: "1.0.0",
    dependencies: [],
    enabled: true,
  },
  async init() {
    // Initialize server-side plugin resources.
  },
  extensions: [],
  widgets: [],
};

This is a shape example, not a complete plugin installer. Registration, enable/disable persistence, route discovery and UI rendering must be wired through the plugin registry/provider and your app's route integration.

Provider and persistence#

PluginServiceProvider is exported from the root. The registry has a repository contract (IPluginRepository) with methods to list/find plugin statuses, seed new plugin statuses, upsert status and store JSON configuration. PluginStatusRecord tracks id, enabled, installed, system, optional config and last step. The package depends on @veap/auth, @veap/database, @veap/intl, and @veap/kernel.

UI extension points#

Client-only React extension components are available through @veap/plugins/client. The source defines extension components with point, target, component, priority and optional role/permission metadata; widgets include an area, component, priority and layout hints. A role/permission annotation is not a substitute for server-side authorization of data or actions.

Routes and middleware#

The package exports router infrastructure through @veap/plugins/router. The source tree includes route discovery, scanning, matching, route trees, middleware, handlers, React rendering and error-boundary modules. IPlugin.routeTree can be a route node or a function returning one. Because route semantics depend on the installed router integration, use the exact RouteNode declaration and tests when authoring dynamic segments, layouts, parallel routes or rewrite rules.

CLI#

The source contains CLI commands for adding/ejecting plugins and generating plugin scaffolds, as well as package-manager detection. Check the installed package's bin field and CLI source before relying on a particular executable name or argument syntax; those details are intentionally not guessed here.