fastify-decorators

Framework aimed to provide useful TypeScript decorators to implement controllers, services and request handlers, built with Fastify.

Benefits

• Fastify compatible - Built with Fastify and supports all its features and plugins
  • JSON Schema validation - Build JSON Schemas to validate and speedup your requests and replies
  • High performance - Framework adds as less overhead to Fastify as it can
• Highly customizable - Create your controllers, services and their methods as you wish
• 100% TypeScript - Written in TypeScript and comes with all the required typings
• Plugins - Library provides APIs to extend its functionality
  • Simple DI - Provides simple Dependency Injection interface to bind your services
  • TypeDI - Provides integration with TypeDI

Documentation

• Getting started
• Bootstrapping
• Controllers
• Request Handlers
• Testing
• Plugins Development
• Migration guide (V4)

Fastify versions support

Fastify Decorators	Fastify
1.x	2.x
2.x	2.x
< 3.12.x	3.x
>= 3.12.x	3.x & 4.x
4.x	4.x

Alternatives

• NestJS - A progressive Node.js framework for building efficient, reliable and scalable server-side applications.
• Fastify Resty - Modern and declarative REST API framework for superfast and oversimplification backend development, build on top of Fastify and TypeScript.

Getting started

Hello! Thank you for checking out fastify-decorators!

This documents aims to be gentle introduction to the fastify-decorators and its usages.

Prerequisites

• Typescript
• Fastify
• typings for NodeJS (@types/node package installed)

Install

Install with npm

npm i fastify-decorators --save

Install with yarn

yarn add fastify-decorators

Additional TypeScript configuration

Fastify-decorators requires experimentalDecorators feature to be enabled. For this you need to update your TypeScript config:

tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

Note: if you struggle which target please refer to table below:

Node version	target
14.x	es2020
16.x	es2021
18.x	es2022

fastify-decorators itself use "target": "es2018" to support NodeJS 10+ (see Node.js ES2018 Support).

Your first server

Request handler way

Let's write your first server with request handler:

Project structure:

 ├── index.ts
 ├── handlers
 │    └── first.handler.ts
 └── tsconfig.json

index.ts:

import { bootstrap } from 'fastify-decorators';

// Require the framework and instantiate it
const instance = require('fastify')();

// Register handlers auto-bootstrap
instance.register(bootstrap, {
  // Specify directory with our handler
  directory: new URL(`handlers`, import.meta.url),

  // Specify mask to match only our handler
  mask: /\.handler\./,
});

// Run the server!
instance.listen(3000);

handlers/first.handler.ts:

import { GET, RequestHandler } from 'fastify-decorators';

@GET({
  url: '/hello',
})
export default class FirstHandler extends RequestHandler {
  async handle() {
    return 'Hello world!';
  }
}

Controllers way

fastify-decorators also provides way to build controllers with multiple handlers:

Project structure:

 ├── index.ts
 ├── controllers
 │    └── first.controller.ts
 └── tsconfig.json

index.ts:

import { bootstrap } from 'fastify-decorators';

// Require the framework and instantiate it
const instance = require('fastify')();

// Register handlers auto-bootstrap
instance.register(bootstrap, {
  // Specify directory with our controllers
  directory: new URL(`controllers`, import.meta.url),

  // Specify mask to match only our controllers
  mask: /\.controller\./,
});

// Run the server!
instance.listen(3000);

controllers/first.controller.ts:

import { Controller, GET } from 'fastify-decorators';

@Controller({ route: '/' })
export default class FirstController {
  @GET({ url: '/hello' })
  async helloHandler() {
    return 'Hello world!';
  }

  @GET({ url: '/goodbye' })
  async goodbyeHandler() {
    return 'Bye-bye!';
  }
}

Also, we need to enable experimentalDecorators feature in our TypeScript config

tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

Build and run server

After all our files done we have to build server before we can run it:

1. Add to our package.json script to build server:

   "scripts": {
     "build": "tsc"
   }
   

2. Run build script With npm:

   npm run build
   

   with yarn:

   yarn build
   

3. Start server

   node index.ts
   

Awesome, that was easy.

License

This project licensed under MIT License