fastify-plugin
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.0 • Public • Published

    fastify-plugin

    CI workflow js-standard-style

    fastify-plugin is a plugin helper for Fastify.

    When you build plugins for Fastify and you want that them to be accessible in the same context where you require them, you have two ways:

    1. Use the skip-override hidden property
    2. Use this module

    Note: the v2.x series of this module covers Fastify v3. For Fastify v2 support refert to the v1.x series.

    Usage

    fastify-plugin can do three things for you:

    • Add the skip-override hidden property
    • Check the bare-minimum version of Fastify
    • Pass some custom metadata of the plugin to Fastify

    Example:

    const fp = require('fastify-plugin')
     
    module.exports = fp(function (fastify, opts, next) {
      // your plugin code
      next()
    })

    Metadata

    In addition if you use this module when creating new plugins, you can declare the dependencies, the name and the expected Fastify version that your plugin needs.

    Fastify version

    If you need to set a bare-minimum version of Fastify for your plugin, just add the semver range that you need:

    const fp = require('fastify-plugin')
     
    module.exports = fp(function (fastify, opts, next) {
      // your plugin code
      next()
    }, { fastify: '3.x' })

    If you need to check the Fastify version only, you can pass just the version string.

    You can check here how to define a semver range.

    Name

    Fastify uses this option to validate dependency graph. On one hand it makes sure that no name collision occurs. On the other hand it makes possible to perform dependency check.

    const fp = require('fastify-plugin')
     
    function plugin (fastify, opts, next) {
      // your plugin code
      next()
    }
     
    module.exports = fp(plugin, {
      fastify: '3.x',
      name: 'your-plugin-name'
    })

    Dependencies

    You can also check if the plugins and decorators which your plugin intend to use are present in the dependency graph.

    Note: This is the point where registering name of the plugins become important, because you can reference plugin dependencies by their name.

    const fp = require('fastify-plugin')
     
    function plugin (fastify, opts, next) {
      // your plugin code
      next()
    }
     
    module.exports = fp(plugin, {
      fastify: '3.x',
      decorators: {
        fastify: ['plugin1', 'plugin2'],
        reply: ['compress']
      },
      dependencies: ['plugin1-name', 'plugin2-name']
    })

    Bundlers and Typescript

    fastify-plugin adds a .default and [name] property to the passed in function. The type definition would have to be updated to leverage this.

    Known Issue: TypeScript Contextual Inference

    Documentation Reference

    It is common for developers to inline their plugin with fastify-plugin such as:

    fp((fastify, opts, next) => { next() })
    fp(async (fastify, opts) => { return })

    TypeScript can sometimes infer the types of the arguments for these functions. Plugins in fastify are recommended to be typed using either FastifyPluginCallback or FastifyPluginAsync. These two definitions only differ in two ways:

    1. The third argument next (the callback part)
    2. The return type FastifyPluginCallback or FastifyPluginAsync

    At this time, TypeScript inference is not smart enough to differentiate by definition argument length alone.

    Thus, if you are a TypeScript developer please use on the following patterns instead:

    // Callback
     
    // Assign type directly
    const pluginCallback: FastifyPluginCallback = (fastify, options, next) => { }
    fp(pluginCallback)
     
    // or define your own function declaration that satisfies the existing definitions
    const pluginCallbackWithTypes = (fastify: FastifyInstance, options: FastifyPluginOptions, next: (error?: FastifyError) => void): void => { }
    fp(pluginCallbackWithTypes)
    // or inline
    fp((fastify: FastifyInstance, options: FastifyPluginOptions, next: (error?: FastifyError) => void): void => { })
     
    // Async
     
    // Assign type directly
    const pluginAsync: FastifyPluginAsync = async (fastify, options) => { }
    fp(pluginAsync)
     
    // or define your own function declaration that satisfies the existing definitions
    const pluginAsyncWithTypes = async (fastify: FastifyInstance, options: FastifyPluginOptions): Promise<void> => { }
    fp(pluginAsyncWithTypes)
    // or inline
    fp(async (fastify: FastifyInstance, options: FastifyPluginOptions): Promise<void> => { })

    Acknowledgements

    This project is kindly sponsored by:

    License

    Licensed under MIT.

    Install

    npm i fastify-plugin

    DownloadsWeekly Downloads

    322,024

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    26.3 kB

    Total Files

    18

    Last publish

    Collaborators

    • avatar
    • avatar