@uscreen.de/fastify-app

fastify-app

Opinionated feature pack (of packages) to bootstrap a fastify app

Features

• decorates your app with name, version and root-path read from package.json
• decorates your app with any given config
• provides OpenAPI 3.0 docs by use of @fastify/swagger & Scalar
• enables extra security headers as provided by helmet @fastify/helmet
• provides extra sensible defaults provided by @fastify/sensible
• uses @fastify/autoload to load plugins, models, services, whatever from configurable directories
• provides monitoring healthcheck endpoint by use of under-pressure

All those features are ready setup with defaults, that may be customized further to your likings.

Get Started (cli)

Easy start by pnpm create cli command to create a new fastify-app from scratch instead of manually setting up a new fastify instance, like so:

$ pnpm create @uscreen.de/fastify-app new-app

It will create a directory called new-app inside the current folder. Inside that directory, it will generate the initial project structure:

new-app
├── .env
├── .env.example
├── .gitignore
├── README.md
├── app
│   ├── app.js
│   ├── config.js
│   ├── plugins
│   │   └── noop.js
│   ├── schemas.js
│   ├── server.js
│   └── services
│       └── noop.js
├── package.json
└── test
    ├── app
    │   └── noop.test.js
    └── helper.js

Install (manual)

$ pnpm add @uscreen.de/fastify-app # or use npm -i

Example (manual)

Minimal example:

import defaultApp from '@uscreen.de/fastify-app'

// register with defaults
fastify.register(defaultApp)

With default server options for logging, etc.

import Fastify from 'fastify'
import defaultApp, { options } from '@uscreen.de/fastify-app'

// create fastify instance with default options
const fastify = Fastify(options())

// register with defaults
fastify.register(defaultApp)

This enables all default features and exposes some extra routes, like:

• GET /docs - autogenerated OpenAPI 3.0 documentation of all endpoint
• GET /health - healthcheck endpoint return HTTP 200 {"status":"ok"}

Options

All options get validated and defaulted to a defined json-schema you can check in config.js Overview of options:

option	Description	Default	Example
autoloads	array of directories @fastify/autoload should load your fastify plugins from. Please consider reading Loading order of your plugins	[]	['./plugins', './services']
swagger	object configuring @fastify/swagger to generate Swagger2/OpenAPI3 docs from your routes	{exposeRoute: true, openapi:{}}	{exposeRoute: '/docs'}
swagger.scalar	object configuring @scalar/fastify-api-reference to configure the scalar client. Read Configuration for more details.	{}	{theme: 'solarized'}
health	object configuring under-pressure to provide a monitoring healthcheck route for your app	{exposeStatusRoute: true}	{exposeStatusRoute: '/health'}
contentSecurityPolicy	object configuring helmet to set CSR headers on each response	{contentSecurityPolicy: false}	{contentSecurityPolicy: {directives: {defaultSrc: ["'self'"]}}}

Howto add custom healthchecks

decorate your healthCheck option with a custom function returning truthy on success, ie.:

import fastifyApp from '@uscreen.de/fastify-app'
import fp from 'fastify-plugin'
import schemas from './schemas.js'

export default fp(async (fastify, opts, next) => {
  /**
   * add schemas
   */
  fastify.register(schemas)

  /**
   * configure healthCheck function for health
   */
  opts.health = {
    ...opts.health,

    healthCheck: async () => {
      /**
       * check for proper mongo conenction
       */
      const collections = await fastify.mongo.db.collections()

      /**
       * check for proper nats connection
       */
      const natsConnected = await fastify.nats.testConnection()

      /**
       * check for proper redis connection
       */
      const redisConnected = await fastify.redis.ping()

      /**
       * true if all tests passed
       */
      return collections && natsConnected && redisConnected && true
    }
  }

  /**
   * register app
   */
  fastify.register(fastifyApp, opts)

  next()
})

Roadmap

• TBD

Changelog

3.3.0

Changed

• removed ci tests for Node.js v18
• updated & upgraded dependencies

3.2.0

Fixed

• fixed docs for custom healthcheck
• fixed app.version in HTTP headers

Changed

• updated dependencies
• upgraded helmet to v13.x, fastify v5.5.x

Added

• support for Node.js v24

3.1.0

Added

• config.logger.name to set logger name as config injection, ie: config.logger.name = 'my-app'

3.0.1

Changed

• update readme to changes in @uscreen.de/create-fastify-app

3.0.0

Added

• support for Node.js v22

Changed

• use Scalar instead of Swagger-UI
• use @fastify/one-line-logger instead of pino-pretty

Removed

• support for Swagger (OpenAPI v2)

2.1.0

Changed

• make options method pass through trustProxy property.

2.0.0

Changed

• upgrade to fastify@5.x

1.1.0

Changed

• make options method pass through ajv property.

1.0.0

Changed

• switch to ESM only
• upgrade to fastify@4.x

Added

• a server options factory providing defaults for logging and generateId options([config])

0.8.3

Changed

• replaced fastify-[module] with their scoped versions (@fastify/autoload, @fastify/helmet, @fastify/sensible, @fastify/swagger)

Fixed

• fixed deprecation warning
• fixed swagger /docs routes

0.8.0

Changed

• upgrade all deps including major versions, like fastify-helmet@4.x
• replace fastify-swagger with fastify-swagger
• upgrade node LTS (16)

0.7.0

Changed

• upgraded all deps including major versions, like fastify-plugin@3.x
• upgrade node LTS (14)

0.6.0

Changed

• upgraded all deps including major versions, like fastify@3.6.x, env-schem@2.0.0
• uses shared config @uscreen.de/eslint-config-prettystandard-node

0.5.1

Fixed

• fastify 3.6.x decorates fastify.version which broke

Added

• decorate fastify.app.version, fastify.app.name, and fastify.app.root

Changed

• skip decoration of any fastify.<decorator> if already declared

0.5.0

• upgraded to fastify 3.x with backward compatible defaults

0.4.0

• added alias of health <-> healthCheck

0.3.0

• moved cli to separate package @uscreen.de/create-fastify-app

0.2.0

• added cli

0.1.0

• added tests (100% coverage)

0.0.0

• project setup, linting, guidlines

License

Licensed under MIT.

Published, Supported and Sponsored by u|screen