Plugins

Plugins add functionality to your Velox TS application. Velox TS is built on Fastify’s plugin system.

Using Plugins

Velox TS plugins are typically factory functions that return a plugin:

import { veloxApp } from '@veloxts/velox';
import { databasePlugin } from '@veloxts/orm';
import { authPlugin } from '@veloxts/auth';
import { db } from './config/database.js';

const app = await veloxApp({ port: 3030 });

// databasePlugin is a factory - pass options to create the plugin
await app.register(databasePlugin({ client: db }));

// authPlugin is also a factory - pass full config object
await app.register(authPlugin({
  jwt: {
    secret: process.env.JWT_SECRET!,
    refreshSecret: process.env.JWT_REFRESH_SECRET,
    accessTokenExpiry: '15m',
    refreshTokenExpiry: '7d',
  },
  userLoader: async (userId) => {
    return db.user.findUnique({ where: { id: userId } });
  },
}));

await app.start();

Built-in Plugins

Package	Plugin	Purpose
@veloxts/orm	databasePlugin({ client })	Prisma database connection
@veloxts/auth	authPlugin({ jwt, userLoader, ... })	JWT authentication
@veloxts/router	swaggerPlugin	OpenAPI documentation
@veloxts/cache	cachePlugin({ driver, config })	Multi-driver caching
@veloxts/queue	queuePlugin({ driver, config })	Background job processing
@veloxts/mail	mailPlugin({ driver, config })	Email sending
@veloxts/storage	storagePlugin({ driver, ... })	File storage

Creating Plugins

Use definePlugin to create type-safe plugins:

import { definePlugin } from '@veloxts/core';

interface MyPluginOptions {
  apiKey: string;
  timeout?: number;
}

export const myPlugin = definePlugin<MyPluginOptions>({
  name: 'my-plugin',
  version: '1.0.0',
  register: async (server, options) => {
    const { apiKey, timeout = 5000 } = options;

    // Add hooks
    server.addHook('onRequest', async (request) => {
      // ...
    });

    // Add decorators
    server.decorate('myService', createService(apiKey));

    // Add shutdown hook
    server.addHook('onClose', async () => {
      // Cleanup resources
    });
  },
});

// Usage
await app.register(myPlugin, { apiKey: 'xxx' });

Fastify Plugins

You can use any Fastify plugin directly:

import cors from '@fastify/cors';
import helmet from '@fastify/helmet';

await app.register(cors, { origin: true });
await app.register(helmet);

Related Content

• Application - App lifecycle
• Context - Request context
• Configuration - Plugin configuration