Skip to content

Set of Typescript decorators to build Fastify server with controllers, services and hooks

License

Notifications You must be signed in to change notification settings

L2jLiga/fastify-decorators

Repository files navigation

Fastify decorators

npm version npm

License: MIT Node.js CI codecov

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

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