skills/mindrally/skills/fastify-typescript

# fastify-typescript

SKILL.md

# Fastify TypeScript Development

You are an expert in Fastify and TypeScript development with deep knowledge of building high-performance, type-safe APIs.

## TypeScript General Guidelines

### Basic Principles

- Use English for all code and documentation
- Always declare types for variables and functions (parameters and return values)
- Avoid using `any` type - create necessary types instead
- Use JSDoc to document public classes and methods
- Write concise, maintainable, and technically accurate code
- Use functional and declarative programming patterns; avoid classes
- Prefer iteration and modularization to adhere to DRY principles

### Nomenclature

- Use PascalCase for types and interfaces
- Use camelCase for variables, functions, and methods
- Use kebab-case for file and directory names
- Use UPPERCASE for environment variables
- Use descriptive variable names with auxiliary verbs: `isLoading`, `hasError`, `canDelete`
- Start each function with a verb

### Functions

- Write short functions with a single purpose
- Use arrow functions for simple operations
- Use async/await consistently throughout the codebase
- Use the RO-RO pattern (Receive an Object, Return an Object) for multiple parameters

### Types and Interfaces

- Prefer interfaces over types for object shapes
- Avoid enums; use maps or const objects instead
- Use Zod for runtime validation with inferred types
- Use `readonly` for immutable properties
- Use `import type` for type-only imports

## Fastify-Specific Guidelines

### Project Structure

    src/
      routes/
        {resource}/
          index.ts
          handlers.ts
          schemas.ts
      plugins/
        auth.ts
        database.ts
        cors.ts
      services/
        {domain}Service.ts
      repositories/
        {entity}Repository.ts
      types/
        index.ts
      utils/
      config/
      app.ts
      server.ts

### Route Organization

- Organize routes by resource/domain
- Use route plugins for modular registration
- Define schemas alongside route handlers
- Use route prefixes for API versioning

    import { FastifyPluginAsync } from 'fastify';

    const usersRoutes: FastifyPluginAsync = async (fastify) => {
      fastify.get('/', { schema: listUsersSchema }, listUsersHandler);
      fastify.get('/:id', { schema: getUserSchema }, getUserHandler);
      fastify.post('/', { schema: createUserSchema }, createUserHandler);
      fastify.put('/:id', { schema: updateUserSchema }, updateUserHandler);
      fastify.delete('/:id', { schema: deleteUserSchema }, deleteUserHandler);
    };

    export default usersRoutes;

### Schema Validation with JSON Schema / Ajv

- Define JSON schemas for all request/response validation
- Use @sinclair/typebox for type-safe schema definitions
- Leverage Fastify's built-in Ajv integration

    import { Type, Static } from '@sinclair/typebox';

    const UserSchema = Type.Object({
      id: Type.String({ format: 'uuid' }),
      name: Type.String({ minLength: 1 }),
      email: Type.String({ format: 'email' }),
      createdAt: Type.String({ format: 'date-time' }),
    });

    type User = Static<typeof UserSchema>;

    const createUserSchema = {
      body: Type.Object({
        name: Type.String({ minLength: 1 }),
        email: Type.String({ format: 'email' }),
      }),
      response: {
        201: UserSchema,
        400: ErrorSchema,
      },
    };

### Plugins and Decorators

- Use plugins for shared functionality
- Decorate Fastify instance with services and utilities
- Register plugins with proper encapsulation

    import fp from 'fastify-plugin';

    const databasePlugin = fp(async (fastify) => {
      const prisma = new PrismaClient();

      await prisma.$connect();

      fastify.decorate('prisma', prisma);

      fastify.addHook('onClose', async () => {
        await prisma.$disconnect();
      });
    });

    export default databasePlugin;

### Prisma Integration

- Use Prisma as the ORM for database operations
- Create repository classes for data access
- Use transactions for complex operations

    class UserRepository {
      constructor(private prisma: PrismaClient) {}

      async findById(id: string): Promise<User | null> {
        return this.prisma.user.findUnique({ where: { id } });
      }

      async create(data: CreateUserInput): Promise<User> {
        return this.prisma.user.create({ data });
      }
    }

### Error Handling

- Use Fastify's built-in error handling
- Create custom error classes for domain errors
- Return consistent error responses

    import { FastifyError } from 'fastify';

    class NotFoundError extends Error implements FastifyError {
      code = 'NOT_FOUND';
      statusCode = 404;

      constructor(resource: string, id: string) {
        super(`${resource} with id ${id} not found`);
        this.name = 'NotFoundError';
      }
    }

    // Global error handler
    fastify.setErrorHandler((error, request, reply) => {
      const statusCode = error.statusCode || 500;

      reply.status(statusCode).send({
        error: error.name,
        message: error.message,
        statusCode,
      });
    });

### Testing with Jest

- Write unit tests for services and handlers
- Use integration tests for routes
- Mock external dependencies

    import { build } from '../app';

    describe('Users API', () => {
      let app: FastifyInstance;

      beforeAll(async () => {
        app = await build();
      });

      afterAll(async () => {
        await app.close();
      });

      it('should list users', async () => {
        const response = await app.inject({
          method: 'GET',
          url: '/api/users',
        });

        expect(response.statusCode).toBe(200);
        expect(JSON.parse(response.payload)).toBeInstanceOf(Array);
      });
    });

### Performance

- Fastify is one of the fastest Node.js frameworks
- Use schema validation for automatic serialization optimization
- Enable logging only when needed in production
- Use connection pooling for database connections

### Security

- Use @fastify/helmet for security headers
- Implement rate limiting with @fastify/rate-limit
- Use @fastify/cors for CORS configuration
- Validate all inputs with JSON Schema
- Use JWT for authentication with @fastify/jwt

Weekly Installs
48
Repository
mindrally/skills
First Seen
Jan 25, 2026
Security Audits
Gen Agent Trust Hub Pass
Socket Pass
Snyk Pass
Installed on
claude-code 37
gemini-cli 36
opencode 35
antigravity 31
codex 30
github-copilot 29