Custom Plugin
Plugins in Vercube provide a way to extend the framework's functionality by registering services, controllers, and other components. Every plugin extends the BasePlugin class and implements the use() method.
How Plugins Work
Plugins are added to your application during the setup phase using app.addPlugin(). When a plugin is added, Vercube calls its use() method with the application instance, allowing the plugin to register its services and configure the application.
import { createApp } from '@vercube/core';
import { MyPlugin } from './plugins/MyPlugin';
const app = createApp({
setup: async (app) => {
app.addPlugin(MyPlugin);
}
});
BasePlugin Class
The BasePlugin class is the foundation for all plugins.
export class BasePlugin<T = unknown> {
/**
* The name of the plugin.
*/
public name: string;
/**
* Uses the plugin with the given app.
*/
public use(app: App, options?: T): void | Promise<void> {}
}
Properties
| Property | Type | Description |
|---|---|---|
name | string | The unique name of the plugin |
Methods
use(app, options?)
Called when the plugin is added to the application. Use this method to register services, controllers, and configure the app.
| Parameter | Type | Description |
|---|---|---|
app | App | The application instance |
options | T | Optional configuration options |
Returns: void | Promise<void>
Creating a Custom Plugin
Here's an example plugin that registers services and a controller with configuration options:
import { BasePlugin } from '@vercube/core';
import type { App } from '@vercube/core';
export class MetricsPlugin extends BasePlugin {
public override name: string = 'MetricsPlugin';
public override use(app: App): void {
// Bind services
app.container.bind(MetricsService);
// Bind controller for API endpoints
app.container.bind(MetricsController);
}
}
Usage:
import { createApp } from '@vercube/core';
import { MetricsPlugin } from './plugins/MetricsPlugin';
const app = createApp({
setup: async (app) => {
app.addPlugin(MetricsPlugin);
}
});
use() method return a Promise<void> for async initialization.Adding Plugins
Plugins are added in the application setup:
import { createApp } from '@vercube/core';
import { SchemaPlugin } from '@vercube/schema';
import { WebsocketPlugin } from '@vercube/ws';
import { MCPPlugin } from '@vercube/mcp';
const app = createApp({
setup: async (app) => {
// Add plugins without options
app.addPlugin(SchemaPlugin);
app.addPlugin(WebsocketPlugin);
app.addPlugin(MCPPlugin);
// Add plugin with options
app.addPlugin(CachePlugin, { driver: 'redis' });
}
});
API Reference
BasePlugin<T>
Abstract base class for all plugins.
class BasePlugin<T = unknown> {
public name: string;
public use(app: App, options?: T): void | Promise<void>;
}
Type Parameters:
| Parameter | Description |
|---|---|
T | Type of the options object |
app.addPlugin()
Method to add a plugin to the application.
app.addPlugin(PluginClass);
app.addPlugin(PluginClass, options);
Parameters:
| Parameter | Type | Description |
|---|---|---|
PluginClass | typeof BasePlugin | The plugin class to add |
options | T | Optional configuration for the plugin |