Fastify Plugins

Organize Fastify apps with encapsulated plugins, autoload, and shared decorators.

Recipe

Quick-reference recipe card - copy-paste ready.

import Fastify from "fastify";
import fp from "fastify-plugin";
import autoload from "@fastify/autoload";
import { join } from "node:path";
 
const app = Fastify({ logger: true });
 
// Shared decorator (breaks encapsulation intentionally)
await app.register(fp(async (fastify) => {
  fastify.decorate("db", { query: async (sql: string) => [] });
}));
 
// Autoload all plugins in ./plugins and routes in ./routes
await app.register(autoload, { dir: join(import.meta.dirname, "plugins") });
await app.register(autoload, { dir: join(import.meta.dirname, "routes") });
 
await app.listen({ port: 3000 });

When to reach for this: Any Fastify app beyond a single file. Plugins are the primary modularity unit.

Working Example

src/
  app.ts
  plugins/
    auth.ts
    database.ts
  routes/
    users.ts
    health.ts

// plugins/database.ts
import fp from "fastify-plugin";
 
export default fp(async (fastify) => {
  const pool = { query: async (sql: string) => [{ id: 1 }] };
  fastify.decorate("db", pool);
  fastify.addHook("onClose", async () => {
    // close pool connections
  });
});
 
// routes/users.ts
import { FastifyPluginAsync } from "fastify";
 
const users: FastifyPluginAsync = async (fastify) => {
  fastify.get("/", async () => {
    return fastify.db.query("SELECT * FROM users");
  });
};
 
export default users;
 
// app.ts
import Fastify from "fastify";
import autoload from "@fastify/autoload";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
 
const __dirname = dirname(fileURLToPath(import.meta.url));
const app = Fastify({ logger: true });
 
await app.register(autoload, { dir: join(__dirname, "plugins") });
await app.register(autoload, { dir: join(__dirname, "routes"), options: { prefix: "/api" } });

What this demonstrates:

• fastify-plugin wraps shared plugins for global scope
• @fastify/autoload discovers plugins by directory convention
• onClose hook for cleanup on shutdown
• Route plugins mounted with /api prefix

Deep Dive

How It Works

• register(plugin) creates a new encapsulation context
• Decorators, hooks, and routes inside a plugin are invisible to sibling plugins
• fastify-plugin (fp) lifts a plugin to the parent scope
• Autoload reads directory and registers each file as a plugin

Encapsulation Rules

TypeScript Declaration Merging

import "fastify";
 
declare module "fastify" {
  interface FastifyInstance {
    db: { query: (sql: string) => Promise<unknown[]> };
  }
}

Gotchas

• Decorator not visible in routes - registered in sibling plugin without fp. Fix: wrap with fastify-plugin.
• Circular plugin dependencies - plugin A registers B which registers A. Fix: extract shared deps to a third plugin.
• Autoload order is filesystem order - auth plugin may load after routes. Fix: use plugins/ and routes/ dirs; plugins dir loads first.
• Async plugin without await - routes register before DB is ready. Fix: await app.register(dbPlugin) before routes.
• Missing onClose cleanup - connection pool leaks on SIGTERM. Fix: close pools in onClose.
• Default export vs named - autoload expects export default async function. Fix: follow convention.

Alternatives

FAQs

Related

• Fastify Basics - encapsulation intro
• JSON Schema Validation - shared schemas
• Logging with Pino - logging plugin
• Testing Fastify Apps - plugin isolation tests
• Fastify Best Practices - section checklist

External Related Links

• Fastify - High-performance web framework docs.
• Node.js Best Practices (GitHub) - Curated production best practices.
• Node.js API Documentation - Complete reference for core modules and APIs.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.
• Node.js Design Patterns, 2nd Edition - Earlier edition still useful.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.