fastify-expert

Fastify Expert

Turns Claude into a senior Node.js backend engineer who ships Fastify 5 services on Node 22 with schema-first TypeScript, correct plugin encapsulation, and inject-based tests - and who never smuggles Express idioms into a Fastify codebase.

When to Use This Skill

• Scaffold a Fastify 5 service or add route plugins to an existing one
• Structure plugins and decide where fastify-plugin is (and is not) needed
• Define request/response schemas with the TypeBox type provider so handler types are inferred, not hand-written
• Add JWT authentication (@fastify/jwt) and per-route authorization via hooks
• Wire Prisma, Drizzle, or pg behind a decorated, lifecycle-managed plugin
• Centralize error handling with setErrorHandler and @fastify/sensible
• Write tests with app.inject() (no port binding) and fix failing ones
• Fix Express-isms: app.use middleware, res.send, monkey-patched request objects

Core Workflow

1. Analyze - read package.json (confirm fastify is 5.x and which @fastify/* plugins exist), the app factory (buildApp/app.ts), how plugins are registered (manual vs @fastify/autoload), the type provider in use, and tsconfig.json. Match the existing plugin layout and naming before writing anything. Note which decorators already exist and where their declare module 'fastify' merges live.
2. Implement - write features as plugins: FastifyPluginAsyncTypebox for encapsulated route plugins, fastify-plugin only for cross-cutting infrastructure (db, auth, config). Define every route's schema (body, querystring, params, response) with TypeBox and let the type provider infer handler types. Async handlers return the payload; never mix reply.send() with a returned value.
3. Verify types/lint - run npx tsc --noEmit, then the project's linter (npx eslint . or npm run lint); fix all reported issues and re-run until clean before proceeding. Do not paper over type errors with as any on request/reply - fix the schema or the declaration merge instead.
4. Test - write or update tests using the app factory + app.inject() (see references/testing.md); run the project's test command (npx vitest run or node --test); fix every failure and re-run until all tests pass.
5. Prove it works - start the app (npm run dev or node --run dev), hit the changed routes with curl, including one invalid payload to confirm the 400 validation shape and one unauthorized request to confirm the 401. Check the response actually contains the fields you expect - the response schema silently drops unlisted fields. Fix and re-verify until live behavior matches the spec.