Skip to content
Skills Library
Programming · Building & coding

fastify

/fastify

Fastify is a fast Node.js web framework for building JSON APIs, with JSON Schema validation and serialization, an encapsulated plugin system and lifecycle hooks. Use when the user wants to build or test a Fastify 5 REST API, add schema validation, JWT auth, a database plugin, CORS, hooks or error handling, or asks about Fastify project structure and plugin encapsulation.

Repository
skills ↗
Licence
Apache-2.0
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Fastify is a fast Node.js web framework for building JSON APIs, with JSON Schema validation and serialization, an encapsulated plugin system and lifecycle hooks. Use when the user wants to build or test a Fastify 5 REST API, add schema validation, JWT auth, a database plugin, CORS, hooks or error handling, or asks about Fastify project structure and plugin encapsulation.

Original author description

Fastify is a fast Node.js web framework for building JSON APIs, with JSON Schema validation and serialization, an encapsulated plugin system and lifecycle hooks. Use when the user wants to build or test a Fastify 5 REST API, add schema validation, JWT auth, a database plugin, CORS, hooks or error handling, or asks about Fastify project structure and plugin encapsulation.

How it works

  1. Overview
  2. Instructions
  3. Examples
  4. Guidelines
Original SKILL.md headings · 261 lines, 1,258 words
SKILL.md preview
---
name: fastify
description: >-
  Fastify is a fast Node.js web framework for building JSON APIs, with JSON Schema validation and serialization, an encapsulated plugin system and lifecycle hooks. Use when the user wants to build or test a Fastify 5 REST API, add schema validation, JWT auth, a database plugin, CORS, hooks or error handling, or asks about Fastify project structure and plugin encapsulation.
license: Apache-2.0
compatibility: 'Node.js 20.11+ (Fastify 5; checked with 5.12.7), npm, pnpm or yarn'
metadata:
  author: terminal-skills
  version: 1.1.0
  repository: https://github.com/fastify/fastify
  category: development
  tags: "node, javascript, api, rest, plugins"
---

# Fastify

## Overview

Fastify is a low-overhead Node.js web framework. Requests are validated and responses serialized through JSON Schema, and code is organized in encapsulated plugins. This skill targets Fastify 5 (Node.js 20 or newer; the examples use `import.meta.dirname`, which needs 20.11+). Fastify 5 needs a full JSON Schema object for `querystring`, `params`, `body` and responses (the shorthand without `type: 'object'` was removed), and `listen()` takes an options object, not positional arguments.

## Instructions

### Install

```bash
mkdir articles-api && cd articles-api
npm init -y
npm pkg set type=module
npm i fastify @fastify/autoload @fastify/sensible @fastify/cors @fastify/jwt fastify-plugin pg
```

### Layout

```
src/
├── app.js             # app factory (also used by tests)
├── server.js          # entry point
├── plugins/           # shared plugins, wrapped in fastify-plugin
│   ├── db.js
│   └── auth.js
└── routes/
    └── articles/
        ├── index.js   # route handlers
        └── schema.js  # JSON schemas
test/
└── articles.test.js
```

### App factory and entry point

```javascript
// src/app.js — autoload plugins, then routes under /api
import Fastify from 'fastify';
import autoload from '@fastify/autoload';
import sensible from '@fastify/sensible';
import cors from '@fastify/cors';
import { join } from 'node:path';

export function buildApp(opts = {}) {
  const app = Fastify({ logger: true, ...opts });

  app.register(sensible);
  app.register(cors, { origin: process.env.CORS_ORIGIN?.split(',') ?? false });
  app.register(autoload, { dir: join(import.meta.dirname, 'plugins') });
  app.register(autoload, {
    dir: join(import.meta.dirname, 'routes'),
    options: { prefix: '/api' },
  });

  return app;
}
```

```javascript
// src/server.js
import { buildApp } from './app.js';

const app = buildApp();
try {
  await app.listen({ port: 3000, host: '127.0.0.1' });
} catch (err) {
  app.log.error(err);
  process.exit(1);
}
```

Bind to `127.0.0.1` for local work. Use `0.0.0.0` only inside a container where a proxy fronts the service.

### Schemas and routes

```javascript
// src/routes/articles/schema.js
export const articleSchema = {
  type: 'object',
  properties: {
    id: { type: 'integer' },
    title: { type: 'string' },
    body: { type: 'string' },
    created_at: { type: 'string', format: 'date-time' },
  },
};

export const listArticlesSchema = {
  querystring: {
    type: 'object',
    properties: {
      page: { type: 'integer', minimum: 1, default: 1 },
      limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
    },
  },
  response: { 200: { type: 'array', items: articleSchema } },
};

export const createArticleSchema = {
  body: {
    type: 'object',
    required: ['title', 'body'],
    additionalProperties: false,
    properties: {
      title: { type: 'string', minLength: 1, maxLength: 200 },
      body: { type: 'string' },
    },
  },
  response: { 201: articleSchema },
};
```

```javascript
// src/routes/articles/index.js
import { listArticlesSchema, createArticleSchema } from './schema.js';

export default async function articleRoutes(fastify) {
  fastify.get('/', { schema: listArticlesSchema }, async (request) => {
    const { page, limit } = request.query;   // already coerced to numbers, defaults applied
    const { rows } = await fastify.db.query(
      'SELECT * FROM articles ORDER BY created_at DESC LIMIT $1 OFFSET $2',
      [limit, (page - 1) * limit]
    );
    return rows;
  });

  fastify.get('/:id', {
    schema: { params: { type: 'object', properties: { id: { type: 'integer' } } } },
  }, async (request, reply) => {
    const { rows } = await fastify.db.query('SELECT * FROM articles WHERE id = $1', [request.params.id]);
    if (!rows[0]) return reply.notFound();
    return rows[0];
  });

  fastify.post('/', { schema: createArticleSchema, onRequest: [fastify.authenticate] }, async (request, reply) => {
    const { title, body } = request.body;
    const { rows } = await fastify.db.query(
      'INSERT INTO articles (title, body) VALUES ($1, $2) RETURNING *',
      [title, body]
    );
    return reply.code(201).send(rows[0]);
  });
}
```

### Plugins

```javascript
// src/plugins/db.js — pg pool shared as fastify.db
import fp from 'fastify-plugin';
import pg from 'pg';

export default fp(async function dbPlugin(fastify) {
  const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
  fastify.decorate('db', pool);
  fastify.addHook('onClose', async () => { await pool.end(); });
});
```

```javascript
// src/plugins/auth.js — JWT verification as fastify.authenticate
import fp from 'fastify-plugin';
import jwt from '@fastify/jwt';

export default fp(async function authPlugin(fastify) {
  fastify.register(jwt, { secret: process.env.JWT_SECRET });

  fastify.decorate('authenticate', async function (request, reply) {
    try {
      await request.jwtVerify();
    } catch (err) {
      return reply.unauthorized();
    }
  });
});
```

Set `JWT_SECRET` (a random 32-byte value) in the environment; `@fastify/jwt` refuses to start without a secret.

### Hooks and error handling

```javascript
// inside buildApp(): log duration (reply.elapsedTime is built in, in milliseconds)
app.addHook('onResponse', async (request, reply) => {
  request.log.info({ ms: Number(reply.elapsedTime.toFixed(2)), status: reply.statusCode }, 'request completed');
});

// hide internals of 5xx errors, keep validation messages (statusCode 400)
app.setErrorHandler((error, request, reply) => {
  const status = error.statusCode ?? 500;
  if (status >= 500) request.log.error(error);
  reply.code(status).send({
    error: error.name,
    message: status >= 500 ? 'Internal Server Error' : error.message,
  });
});
```

### Testing

```javascript
// test/articles.test.js — run with: JWT_SECRET=test-secret node --test
import { test } from 'node:test';
import assert from 'node:assert';
import { buildApp } from '../src/app.js';

test('GET /api/articles returns rows', async (t) => {
  const app = buildApp({ logger: false });
  await app.ready();
  t.after(() => app.close());
  app.db.query = async () => ({ rows: [{ id: 1, title: 'Hi', body: 'x', created_at: new Date().toISOString() }] });
  const res = await app.inject({ method: 'GET', url: '/api/articles?limit=5' });
  assert.strictEqual(res.statusCode, 200);
  assert.strictEqual(res.json()[0].title, 'Hi');
});

test('POST without token is 401, with token 201, bad body 400', async (t) => {
  const app = buildApp({ logger: false });
  await app.ready();
  t.after(() => app.close());
  app.db.query = async (_s, [title, body]) => ({ rows: [{ id: 2, title, body }] });
  const payload = { title: 'T', body: 'B' };
  assert.strictEqual((await app.inject({ method: 'POST', url: '/api/articles', payload })).statusCode, 401);
  const token = app.jwt.sign({ sub: 'u1' });
  const ok = await app.inject({ method: 'POST', url: '/api/articles', payload, headers: { authorization: `Bearer ${token}` } });
  assert.strictEqual(ok.statusCode, 201);
  const bad = await app.inject({ method: 'POST', url: '/api/articles', payload: { title: '' }, headers: { authorization: `Bearer ${token}` } });
  assert.strictEqual(bad.statusCode, 400);
  const lim = await app.inject({ method: 'GET', url: '/api/articles?limit=1000' });
  assert.strictEqual(lim.statusCode, 400);
});
```

`app.inject` runs the request in-process without opening a port. Replacing `app.db.query` keeps the test off a real database; use a disposable Postgres for integration tests.

## Examples

### Example 1: Add a validated endpoint

**User request:** "Add POST /api/articles that requires a title up to 200 characters and a body, and only logged-in users can call it."

The agent writes `createArticleSchema` with `required: ['title', 'body']` and `additionalProperties: false`, and attaches `onRequest: [fastify.authenticate]` to the route. A call without a token returns 401, a call with `{ "title": "" }` returns 400 `body must have required property 'body'`, and a valid call returns 201 with the row. Only the properties listed in the 201 response schema are serialized.

### Example 2: Paginate a list safely

**User request:** "GET /api/articles?limit=1000 should not hit the database with 1000 rows."

The agent adds a `querystring` schema with `limit` as an integer with `maximum: 100` and `default: 20`. Fastify coerces `?page=2` to the number 2, applies defaults, and answers `?limit=1000` with 400 `querystring/limit must be <= 100` before the handler runs.

## Guidelines

- Wrap shared plugins (db, auth) in `fastify-plugin`; without it, decorators stay private to the child context and sibling routes cannot see them.
- Put response schemas on every route: they strip unlisted fields (no accidental password hashes) and speed up serialization.
- Async handlers return the value; do not also call `reply.send()`. An async hook that replies must `return reply...` so the chain stops.
- Never commit a fallback JWT secret and never use `origin: true` with CORS in production; list allowed origins in `CORS_ORIGIN`.
- Use parameterized queries (`$1`) only; never interpolate request values into SQL.
- Call `await app.close()` in tests so the pool and server shut down.
- Fastify 4 apps: upgrade notes are in the official V5 migration guide (Node 20+, full JSON schemas, no variadic `listen`).
Files in this package (2)
  • SKILL.md 10 KB
  • _scores.json 2 KB

Versions

RepositoryScoreLicence
This page · TerminalSkills/skills100Apache-2.0
claude-dev-suite/claude-dev-suite100MIT
oriolrius/pki-manager-web90Apache-2.0

Database snapshot: 13.11.2026 · package version d0c11d6a448c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90nodejs-fastify
    Use this skill when building Fastify applications — schema validation, plugin system, hooks, serialization. This skill enforces: JSON Schema validation, plugin encapsulation, schema serializers, Fastify lifecycle hooks. Do NOT use for: Express.js apps, database schema, frontend,…
  • 100fastify-expert
    Use when building or debugging Fastify services - files importing fastify, fastify-plugin, @fastify/* packages, or @sinclair/typebox; projects with a Fastify app factory, route plugins, or app.inject() tests; mentions of Fastify 5, encapsulation, decorators, hooks, TypeBox type…
  • 95fastify-best-practices
    Guides development of Fastify Node.js backend servers and REST APIs using TypeScript or JavaScript. Use when building, configuring, or debugging a Fastify application — including defining routes, implementing plugins, setting up JSON Schema validation, handling errors,…
  • 100fastify-schema-first-service
    Use when building or extending a Fastify application: routes, plugins, hooks, database wiring. Not for testing: use fastify-inject-testing. Not for hardening: use fastify-production-hardening.
  • 95auth0-fastify-api
    Use when securing Fastify API endpoints with JWT Bearer token validation, scope/permission checks, or stateless auth - integrates @auth0/auth0-fastify-api for REST APIs receiving access tokens from frontends or mobile apps.
  • 100fastify-high-performance-apis
    Use this skill when building high-throughput, low-overhead Node.js REST APIs utilizing Fastify's schema compilation and plugins.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.