Plugin System

Plugin composition

Package middleware, commands, handlers, and lifecycle hooks into reusable units.

Install plugins

Mount plugin classes or functions through `bot.plugin()`.

Learn more

Reusable features

Share analytics, auth, logging, or domain behavior across bots.

Learn more

Plugin vs middleware

Know when to reach for a plugin instead of plain middleware.

Learn more

VibeGram's plugin system enables modular feature composition. Plugins encapsulate middleware, commands, and handlers into reusable, installable units.

Quick Start

import { Bot, BotPlugin } from 'vibegram';

// Class-based plugin
class WelcomePlugin implements BotPlugin {
    name = 'welcome';

    install(bot) {
        bot.command('welcome', ctx => ctx.reply('Welcome!'));
    }
}

const bot = new Bot('YOUR_BOT_TOKEN');
bot.plugin(new WelcomePlugin());

Plugin Interface

interface BotPlugin<C extends Context = Context> {
    name: string;
    install(composer: Composer<C>, options?: any): void;
}

Functional Plugins

Use createPlugin() for simpler, configurable plugins:

import { createPlugin } from 'vibegram';

const greetingPlugin = createPlugin('greeting', (bot, opts: { message: string }) => {
    bot.command('greet', ctx => ctx.reply(opts.message));
});

// Install with options
bot.plugin(greetingPlugin({ message: 'Hello from plugin!' }));

Presets

Combine multiple plugins into a single installable preset:

import { Preset } from 'vibegram';

const productionPreset = new Preset('production', [
    new LoggerPlugin(),
    new RateLimitPlugin({ limit: 30 }),
    new SessionPlugin(),
    new CachePlugin({ ttl: 300 }),
]);

bot.plugin(productionPreset);

Creating a Reusable Plugin

// my-analytics-plugin.ts
import { BotPlugin, Composer, Context } from 'vibegram';

export class AnalyticsPlugin implements BotPlugin {
    name = 'analytics';

    constructor(private webhookUrl: string) {}

    install(bot: Composer<Context>) {
        bot.use(async (ctx, next) => {
            const start = Date.now();
            await next();
            const duration = Date.now() - start;

            // Send analytics to your service
            fetch(this.webhookUrl, {
                method: 'POST',
                body: JSON.stringify({
                    updateType: Object.keys(ctx.update).filter(k => k !== 'update_id'),
                    userId: ctx.from?.id,
                    duration,
                }),
            }).catch(() => {});
        });
    }
}

// Usage
bot.plugin(new AnalyticsPlugin('https://analytics.example.com/events'));

Plugin vs Middleware

Feature	Middleware	Plugin
Scope	Single function	Group of middleware + commands
Configuration	Closure/options	Constructor or factory
Reusability	Copy/paste	Import and install
Composition	Manual ordering	Presets combine automatically
Publishing	N/A	Publishable as npm packages