Fastify Plugin Development

This skill provides patterns and conventions for creating Fastify plugins in this repository.

Directory Structure

Plugins are located in app/src/plugins/. Each plugin is a single TypeScript file that exports a default async function wrapped with fastify-plugin.

Plugin Template

import type { FastifyInstance } from "fastify";
import fp from "fastify-plugin";

async function pluginName(fastify: FastifyInstance): Promise<void> {
  // Plugin implementation
}

export default fp(pluginName, {
  name: "plugin-name",
  dependencies: [], // List plugin dependencies if any
});

Best Practices

1. Always use fastify-plugin wrapper: Wrap plugins with fp() to expose decorators to parent scope
2. Declare dependencies: List other plugins this plugin depends on in the options
3. Type augmentation: Extend Fastify types when adding decorators:

declare module "fastify" {
  interface FastifyInstance {
    myDecorator: string;
  }
  interface FastifyRequest {
    customProperty: CustomType;
  }
}

4. ESM imports: Use .js extensions for relative imports (TypeScript compiles to ESM)
5. Node.js builtins: Use node: protocol prefix (e.g., import * as path from "node:path")
6. Type imports: Use import type { ... } from "pkg" for type-only imports

Existing Plugins Reference (16 plugins)

• accepts-serializer.ts - CBOR response serialization with @fastify/accepts-serializer
• auth.ts - Firebase authentication with request.user decorator
• cbor-parser.ts - CBOR request body parsing
• cors.ts - CORS configuration with @fastify/cors
• error-handler.ts - Global error handling with RFC 9457 Problem Details responses
• firebase.ts - Firebase Admin SDK initialization
• helmet.ts - Security headers with @fastify/helmet
• lifecycle.ts - Server lifecycle hooks and graceful shutdown
• logging.ts - Request/response logging with timing
• requestid.ts - Request ID generation and header propagation
• schema-discovery.ts - Schema link header injection for responses
• schema-registry.ts - Shared TypeBox schema registration
• sensible.ts - HTTP error utilities with @fastify/sensible
• swagger.ts - OpenAPI documentation with @fastify/swagger
• under-pressure.ts - Health checks and system pressure monitoring
• vary-header.ts - Vary: Accept header for proper caching

Testing Requirements

Each plugin must have a corresponding test file in app/tests/unit/plugins/. See the vitest-testing skill for testing patterns.

Commands

cd app
npm run build       # Build and verify TypeScript compilation
npm run check       # Run Biome linter and formatter
npm run check:fix   # Auto-fix linting issues
npm run test        # Run all tests including plugin tests

Boundaries

• Do not modify app/src/app.ts unless adding new plugin registration
• Do not add plugins that duplicate existing functionality
• Always add corresponding unit tests for new plugins