{"id":15642720,"url":"https://github.com/eomm/fastify-overview","last_synced_at":"2025-06-10T08:04:30.777Z","repository":{"id":37035788,"uuid":"384732682","full_name":"Eomm/fastify-overview","owner":"Eomm","description":"Build a structure graph of your Fastify application","archived":false,"fork":false,"pushed_at":"2025-06-10T05:05:42.000Z","size":224,"stargazers_count":70,"open_issues_count":7,"forks_count":6,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-06-10T08:04:10.388Z","etag":null,"topics":["developer-tools","development-environment","fastify","fastify-plugin","hacktoberfest","nodejs"],"latest_commit_sha":null,"homepage":"","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/Eomm.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,"zenodo":null},"funding":{"github":"Eomm"}},"created_at":"2021-07-10T15:40:45.000Z","updated_at":"2025-04-10T05:36:39.000Z","dependencies_parsed_at":"2023-12-18T06:27:16.067Z","dependency_job_id":"6931cc65-f2c1-411b-80d9-c07712fcc6db","html_url":"https://github.com/Eomm/fastify-overview","commit_stats":{"total_commits":84,"total_committers":9,"mean_commits":9.333333333333334,"dds":0.6428571428571428,"last_synced_commit":"0e36c1b2b302c3d7c75a07f8f4383a4c94572200"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":"Eomm/fastify-plugin-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eomm%2Ffastify-overview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eomm%2Ffastify-overview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eomm%2Ffastify-overview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eomm%2Ffastify-overview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Eomm","download_url":"https://codeload.github.com/Eomm/fastify-overview/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eomm%2Ffastify-overview/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259033829,"owners_count":22795769,"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":["developer-tools","development-environment","fastify","fastify-plugin","hacktoberfest","nodejs"],"created_at":"2024-10-03T11:57:17.190Z","updated_at":"2025-06-10T08:04:30.726Z","avatar_url":"https://github.com/Eomm.png","language":"JavaScript","readme":"# fastify-overview\n\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n[![ci](https://github.com/Eomm/fastify-overview/actions/workflows/ci.yml/badge.svg)](https://github.com/Eomm/fastify-overview/actions/workflows/ci.yml)\n[![runkit](https://img.shields.io/badge/try%20on-runkit-blue)](https://runkit.com/eomm/fastify-overview-readme)\n\nGet a complete overview of your fastify application!  \nIt gives you a tree structure to understand all the relations between your routes and plugins.\n\nIt tracks:\n\n- 🛣 **ALL** the Fastify routes\n- 🍱 **ALL** the Fastify plugins\n- 🎨 **ALL** the Fastify decorators\n- 🪝 **ALL** the Fastify hooks\n\nDoing so you will get a complete overview of your application and you can:\n\n- optimize your code\n- optimize your application structure\n- find out the application structure (especially if you have joined a new team)\n- automate some documentation tasks\n\nThis plugin is intended to be run only for _development_ purposes.\n\n\n### Visualize the structure\n\nThis plugin provides a detailed data structure of your application. To be able to visualize it, use this plugin together with [`fastify-overview-ui`](https://github.com/nearform/fastify-overview-ui), be sure to check it out!\n\n\n## Install\n\n```\nnpm install fastify-overview\n```\n\n### Compatibility\n\n| Plugin version | Fastify version |\n| ------------- |:---------------:|\n| `^1.0.0` | `^3.0.0` |\n| `^2.0.0` | `^3.0.0` |\n| `^3.0.0` | `^4.0.0` |\n\n\n## Usage\n\nThis plugin is super simple, just add it to your fastify instance and you will get a `overview()` method that will return a tree structure of your application.\n\nThere are 3 things to know:\n\n1. It starts tracking your application after the `await register()` of the plugin:\n    - what happens before, it is **not** tracked. So **this plugin must be the first one** to be registered.\n    - it the `register` is not awaited, the structure will **not** be tracked.\n2. The application structure can be accessed **after** the Fastify instance is `ready`. If you try to get it before the `ready` status, you will get an error.\n3. The structure tracks hooks' name and decorators' name. If you use arrow functions the structure will be useless/unreadable.\n\nHere the code:\n\n```js\nconst fastify = require('fastify')\n\nasync function run() {\n  const app = fastify()\n\n  // await the plugin registration!\n  await app.register(require('fastify-overview'))\n\n  // create your application as usual\n  app.addHook('onSend', function hookRoot () {})\n  app.register(function register1 (instance, opts, next) {\n    instance.addHook('onRequest', function hook1 () {})\n    instance.register(function register2 (sub, opts, next) {\n      sub.addHook('onRequest', function hook2 () {})\n      next()\n    })\n    next()\n  })\n\n  // read your application structure when fastify is ready\n  app.addHook('onReady', function showStructure (done) {\n    const appStructure = app.overview() // 🦄 Here is the magic!\n    console.log(JSON.stringify(appStructure, null, 2))\n    done(null)\n  })\n\n  await app.listen(3000)\n}\nrun()\n```\n\n\n### Structure\n\nThe JSON structure returned by the `overview` method is like the following:\n\n```js\n{\n  \"id\": 0.331, // an internal id number. You can use it to identify the node\n  \"name\": \"pluginName\", // the name of the plugin | app.register(function pluginName (){})\n  \"children\": [ // the children of the fastify instance | instance.register(function subPlugin (){})\n    // it contains the same structure we are describing\n  ], \n  \"decorators\": { // all the instance decorators | app.decorate('foo-bar', 42)\n    \"decorate\": [ { \"name\": \"foo-bar\", \"type\": \"number\" } ], // the decorators' name\n    \"decorateRequest\": [], // app.decorateRequest('foo-bar', 42)\n    \"decorateReply\": [] // app.decorateReply('foo-bar', 42)\n  },\n  \"hooks\": { // all the instance hooks\n    \"onRequest\": [\n      {\n        \"name\": \"hook1\" // the function name: app.addHook('onRequest', function hook1 (){})\n        \"hash\": \"92b002434cd5d8481e7e5562b51df679e2f8d586\" // the function hash. Useful to identify optimizations\n      }\n    ],\n    \"preParsing\": [],\n    \"preValidation\": [],\n    \"preHandler\": [],\n    \"preSerialization\": [],\n    \"onError\": [],\n    \"onSend\": [],\n    \"onResponse\": [],\n    \"onTimeout\": [],\n    \"onListen\": [],\n    \"onReady\": [],\n    \"onClose\": [],\n    \"onRoute\": [],\n    \"onRegister\": []\n  },\n  \"routes\": [ // an array within all the routes in that fastify context\n    {\n      \"method\": \"GET\",\n      \"url\": \"/prefix/hello\", // the complete route's url\n      \"prefix\": \"/prefix\", // the plugin prefix\n      \"hooks\": { // the hooks that are registered in that single route using the route's options\n        \"onRequest\": [],\n        \"preParsing\": [],\n        \"preValidation\": [\n          {\n            \"name\": \"Anonymous function\",\n            \"hash\": \"ade00501a7c8607ba74bf5e13d751da2139c4e60\"\n          }\n        ],\n        \"preHandler\": [\n          {\n            \"name\": \"hook1\",\n            \"hash\": \"9398f5df01879094095221d86a544179e62cee12\"\n          }\n        ],\n        \"preSerialization\": [],\n        \"onError\": [],\n        \"onSend\": [],\n        \"onResponse\": [],\n        \"onTimeout\": []\n      }\n    }\n  ]\n}\n```\n\nNotice that an hook that appears in the parent node, is inherited by the children but it is not listed in the \nchildren's hooks node.\n\nYou can see the previous code output running it on RunKit: [![runkit](https://img.shields.io/badge/try%20on-runkit-blue)](https://runkit.com/eomm/fastify-overview-readme)\n\n\n## Options\n\nYou can pass the following options to the plugin or to the decorator:\n\n```js\napp.register(require('fastify-overview'), {\n  addSource: true, // default: false\n  exposeRoute: true, // default: false\n  exposeRouteOptions: {\n    method: 'POST', // default: 'GET'\n    url: '/customUrl', // default: '/json-overview'\n  }, \n  onRouteDefinition: (opts) =\u003e {\n    return {\n      schema: opts.schema\n    }\n  }, \n  onDecorateDefinition: (decoratorType, decoratorName, decoratorValue) =\u003e {\n     if (value \u0026\u0026 typeof value === 'object' \u0026\u0026 !Array.isArray(value)) {\n        return {\n           staticData: true\n        }\n     }\n     return { utilityFunction: true }\n  }\n})\n\nconst appStructure = app.overview({\n  hideEmpty: true, // default: false\n  routesFilter: function (routeItem) {\n    return routeItem.method.toLowerCase() !== 'get'\n  }\n})\n```\n\n### addSource\n\nOptionally the plugin adds a `source` property to each node of the tree.\nHere an example of the structure with the `addSource` option:\n\n```json\n{\n  \"name\": \"hook1\",\n  \"hash\": \"31d31d981f412085927efb5e9f36be8ba905516a\",\n  \"source\": {\n    \"stackIndex\": 0,\n    \"fileName\": \"/user/foo/project/bar/test/sources/app.js\",\n    \"relativeFileName\": \"test/sources/app.js\",\n    \"lineNumber\": 34,\n    \"columnNumber\": 11,\n    \"functionName\": \"register3\",\n    \"typeName\": null,\n    \"methodName\": null\n  }\n}\n```\n\n### hideEmpty\n\nTo keep the structure light and clean, you can hide empty properties by providing this option to the `overview` decorator.\nFor example, if you do not have any decorator, the `decorators` property will not be present in the structure.\n\nThe properties that can be hidden are:\n- `decorators` and/or its children\n- `hooks` and/or its children\n- `routes`\n\nYou can get both the structure by calling the `overview` method twice:\n\n```js\nconst fullStructure = app.overview()\nconst lightStructure = app.overview({\n  hideEmpty: true, // default: false\n})\n```\n\nHere an example of the cleaned output:\n\n```json\n{\n  \"id\": 0.38902288100060645,\n  \"name\": \"fastify -\u003e fastify-overview\",\n  \"children\": [\n    {\n      \"id\": 0.7086786379705781,\n      \"name\": \"function (instance, opts, next) { next() }\"\n    },\n    {\n      \"id\": 0.6405610832733726,\n      \"name\": \"async function (instance, opts) { -- instance.register(async function (instance, opts) {\",\n      \"children\": [\n        {\n          \"id\": 0.8200459678409413,\n          \"name\": \"async function (instance, opts) { -- instance.decorateReply('oneRep', {})\",\n          \"decorators\": {\n            \"decorateReply\": [\n              { \"name\": \"oneRep\", \"type\": \"object\" }\n            ]\n          }\n        }\n      ]\n    }\n  ],\n  \"hooks\": {\n    \"onRequest\": [\n      {\n        \"name\": \"hook1\",\n        \"hash\": \"31d31d981f412085927efb5e9f36be8ba905516a\"\n      }\n    ]\n  }\n}\n```\n\n### routesFilter\n\nYou can decide which routes to keep based on the predicate provided in the 'routesFilter' property:\n\n```js\napp.overview({\n  hideEmpty: true,\n  routesFilter: function (routeItem) {\n    return routeItem.method.toLowerCase() !== 'get'\n  }\n})\n```\n\n\n### exposeRoute\n\nOptionally, you can expose a route that will return the JSON structure.\nThis parameter accepts a boolean value.\nBy default the route is exposed at `GET /json-overview`.\n\n\u003e Note that if you need to call the route when the host is not localhost, you will need to setup \n\u003e the [`@fastify/cors`](https://github.com/fastify/fastify-cors/) plugin.\n\n### exposeRouteOptions\n\nYou can customize the route's options when `exposeRoute` is set to `true`.\nYou can provide all the [fastify route's options](https://www.fastify.io/docs/latest/Reference/Routes/#routes-options) except the `handler`.\n\n### onRouteDefinition\n\nThis option can be used to determine which properties of the route options are additional included in the overview. \nThe function receives the [RouteOptions](https://github.com/fastify/fastify/blob/62f564d965949bc123184a27a610f214f23e9a49/types/hooks.d.ts#L695) \nobject as the only parameter and must return an object with the desired properties. You can also overwrite the properties \nthat are included in the route overview by default (namely `url`, `method`, `prefix` and `hooks`). You cannot\noverride the `source` property.\n```js\n onRouteDefinition: (routeOptions) =\u003e {\n   return {\n     method: routeOptions.method,\n     url: routeOptions.url.length,\n     prefix: routeOptions.prefix,\n     schema: routeOptions.schema\n   }\n }\n```\nIn this example, the `url` property is overridden and the `url` length is returned instead of the `url`.\n\n### onDecorateDefinition\n\nSimilar to `onRouteDefinition`, this option allows you to control which information about decorators is included in the overview.\nThe passed function is called for `instance`, `request` and `reply` decorators but the decorator type is passed to the function as parameter.\nThe default properties `name` and `type` can also be overwritten here. See the table below for an overview of exactly \nhow the function `onDecorateDefinition(decoratorType, decoratorName, decoratorValue)` is called for the different decorators.\n\n|                 Decorator                 | decoratorType   | decoratorName | decoratorValue    |\n|:-----------------------------------------:|-----------------|---------------|-------------------|\n| `app.decorate('db', {query: () =\u003e {}})`   | decorate        | db            | {query: () =\u003e {}} |\n| `app.decorateRequest('verify', () =\u003e {})` | decorateRequest | verify        | () =\u003e {}          |\n| `app.decorateReply('num', 42)`            | decorateReply   | num           | 42                |\n\nAs an example, the function below returns the nested properties for object values.\n```js\nonDecorateDefinition: (type, name, value) =\u003e {\n   if (value \u0026\u0026 typeof value === 'object' \u0026\u0026 !Array.isArray(value)) {\n      return {\n         recursive: Object.entries(value).map(([key, val]) =\u003e {\n            return {\n               name: key,\n               type: Array.isArray(val) ? 'array' : typeof val\n            }\n         })\n      }\n   } else {\n      return {}\n   }\n}\n```\n\n## License\n\nCopyright [Manuel Spigolon](https://github.com/Eomm), Licensed under [MIT](./LICENSE).\n","funding_links":["https://github.com/sponsors/Eomm"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feomm%2Ffastify-overview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feomm%2Ffastify-overview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feomm%2Ffastify-overview/lists"}