{"id":14969119,"url":"https://github.com/fastify/fastify-plugin","last_synced_at":"2025-05-14T10:11:17.555Z","repository":{"id":19447183,"uuid":"85714038","full_name":"fastify/fastify-plugin","owner":"fastify","description":"Plugin helper for Fastify","archived":false,"fork":false,"pushed_at":"2025-03-30T21:29:44.000Z","size":234,"stargazers_count":211,"open_issues_count":5,"forks_count":43,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-03T20:48:55.817Z","etag":null,"topics":["encapsulation","fastify","fastify-library","versioning"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/fastify-plugin","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"fastify","open_collective":"fastify"}},"created_at":"2017-03-21T14:46:44.000Z","updated_at":"2025-04-02T18:46:11.000Z","dependencies_parsed_at":"2024-01-23T20:11:15.888Z","dependency_job_id":"f23fd6bf-c27d-475b-bda1-fc35ff768d73","html_url":"https://github.com/fastify/fastify-plugin","commit_stats":{"total_commits":254,"total_committers":36,"mean_commits":7.055555555555555,"dds":0.7598425196850394,"last_synced_commit":"0d96c038359e08d1aea6869abf2ed0bc7003339e"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/fastify-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248338363,"owners_count":21087207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["encapsulation","fastify","fastify-library","versioning"],"created_at":"2024-09-24T13:41:09.510Z","updated_at":"2025-04-11T03:38:00.563Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# fastify-plugin\n\n[![CI](https://github.com/fastify/fastify-plugin/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/fastify-plugin/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/fastify-plugin.svg?style=flat)](https://www.npmjs.com/package/fastify-plugin)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)\n\n`fastify-plugin` is a plugin helper for [Fastify](https://github.com/fastify/fastify).\n\nWhen you build plugins for Fastify and you want them to be accessible in the same context where you require them, you have two ways:\n1. Use the `skip-override` hidden property\n2. Use this module\n\n__Note: the v4.x series of this module covers Fastify v4__\n__Note: the v2.x \u0026 v3.x series of this module covers Fastify v3. For Fastify v2 support, refer to the v1.x series.__\n\n## Install\n\n```sh\nnpm i fastify-plugin\n```\n\n## Usage\n`fastify-plugin` can do three things for you:\n- Add the `skip-override` hidden property\n- Check the bare-minimum version of Fastify\n- Pass some custom metadata of the plugin to Fastify\n\nExample using a callback:\n```js\nconst fp = require('fastify-plugin')\n\nmodule.exports = fp(function (fastify, opts, done) {\n  // your plugin code\n  done()\n})\n```\n\nExample using an [async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) function:\n```js\nconst fp = require('fastify-plugin')\n\n// A callback function param is not required for async functions\nmodule.exports = fp(async function (fastify, opts) {\n  // Wait for an async function to fulfill promise before proceeding\n  await exampleAsyncFunction()\n})\n```\n\n## Metadata\nIn 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.\n\n#### Fastify version\nIf you need to set a bare-minimum version of Fastify for your plugin, just add the [semver](https://semver.org/) range that you need:\n```js\nconst fp = require('fastify-plugin')\n\nmodule.exports = fp(function (fastify, opts, done) {\n  // your plugin code\n  done()\n}, { fastify: '5.x' })\n```\n\nIf you need to check the Fastify version only, you can pass just the version string.\n\nYou can check [here](https://github.com/npm/node-semver#ranges) how to define a `semver` range.\n\n#### Name\nFastify uses this option to validate the dependency graph, allowing it to ensure that no name collisions occur and making it possible to perform [dependency checks](https://github.com/fastify/fastify-plugin#dependencies).\n\n```js\nconst fp = require('fastify-plugin')\n\nfunction plugin (fastify, opts, done) {\n  // your plugin code\n  done()\n}\n\nmodule.exports = fp(plugin, {\n  fastify: '5.x',\n  name: 'your-plugin-name'\n})\n```\n\n#### Dependencies\nYou can also check if the `plugins` and `decorators` that your plugin intend to use are present in the dependency graph.\n\u003e *Note:* This is the point where registering `name` of the plugins become important, because you can reference `plugin` dependencies by their [name](https://github.com/fastify/fastify-plugin#name).\n```js\nconst fp = require('fastify-plugin')\n\nfunction plugin (fastify, opts, done) {\n  // your plugin code\n  done()\n}\n\nmodule.exports = fp(plugin, {\n  fastify: '5.x',\n  decorators: {\n    fastify: ['plugin1', 'plugin2'],\n    reply: ['compress']\n  },\n  dependencies: ['plugin1-name', 'plugin2-name']\n})\n```\n\n#### Encapsulate\n\nBy default, `fastify-plugin` breaks the [encapsulation](https://github.com/fastify/fastify/blob/HEAD/docs/Reference/Encapsulation.md) but you can optionally keep the plugin encapsulated.\nThis allows you to set the plugin's name and validate its dependencies without making the plugin accessible.\n```js\nconst fp = require('fastify-plugin')\n\nfunction plugin (fastify, opts, done) {\n  // the decorator is not accessible outside this plugin\n  fastify.decorate('util', function() {})\n  done()\n}\n\nmodule.exports = fp(plugin, {\n  name: 'my-encapsulated-plugin',\n  fastify: '5.x',\n  decorators: {\n    fastify: ['plugin1', 'plugin2'],\n    reply: ['compress']\n  },\n  dependencies: ['plugin1-name', 'plugin2-name'],\n  encapsulate: true\n})\n```\n\n#### Bundlers and Typescript\n`fastify-plugin` adds a `.default` and `[name]` property to the passed in function.\nThe type definition would have to be updated to leverage this.\n\n## Known Issue: TypeScript Contextual Inference\n\n[Documentation Reference](https://www.typescriptlang.org/docs/handbook/functions.html#inferring-the-types)\n\nIt is common for developers to inline their plugin with fastify-plugin such as:\n\n```js\nfp((fastify, opts, done) =\u003e { done() })\nfp(async (fastify, opts) =\u003e { return })\n```\n\nTypeScript 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:\n\n1. The third argument `done` (the callback part)\n2. The return type `FastifyPluginCallback` or `FastifyPluginAsync`\n\nAt this time, TypeScript inference is not smart enough to differentiate by definition argument length alone.\n\nThus, if you are a TypeScript developer please use on the following patterns instead:\n\n```ts\n// Callback\n\n// Assign type directly\nconst pluginCallback: FastifyPluginCallback = (fastify, options, done) =\u003e { }\nfp(pluginCallback)\n\n// or define your own function declaration that satisfies the existing definitions\nconst pluginCallbackWithTypes = (fastify: FastifyInstance, options: FastifyPluginOptions, done: (error?: FastifyError) =\u003e void): void =\u003e { }\nfp(pluginCallbackWithTypes)\n// or inline\nfp((fastify: FastifyInstance, options: FastifyPluginOptions, done: (error?: FastifyError) =\u003e void): void =\u003e { })\n\n// Async\n\n// Assign type directly\nconst pluginAsync: FastifyPluginAsync = async (fastify, options) =\u003e { }\nfp(pluginAsync)\n\n// or define your own function declaration that satisfies the existing definitions\nconst pluginAsyncWithTypes = async (fastify: FastifyInstance, options: FastifyPluginOptions): Promise\u003cvoid\u003e =\u003e { }\nfp(pluginAsyncWithTypes)\n// or inline\nfp(async (fastify: FastifyInstance, options: FastifyPluginOptions): Promise\u003cvoid\u003e =\u003e { })\n```\n\n## Acknowledgments\n\nThis project is kindly sponsored by:\n- [nearForm](https://nearform.com)\n- [LetzDoIt](https://www.letzdoitapp.com/)\n\n## License\n\nLicensed under [MIT](./LICENSE).\n","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Ffastify-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Ffastify-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Ffastify-plugin/lists"}