{"id":13685092,"url":"https://github.com/fastify/fastify-express","last_synced_at":"2025-04-13T20:39:40.079Z","repository":{"id":34257251,"uuid":"173994635","full_name":"fastify/fastify-express","owner":"fastify","description":"Express compatibility layer for Fastify","archived":false,"fork":false,"pushed_at":"2025-04-01T02:37:07.000Z","size":161,"stargazers_count":259,"open_issues_count":5,"forks_count":27,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-06T17:07:20.210Z","etag":null,"topics":["compatibility","express","fastify","fastify-plugin"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@fastify/express","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":"2019-03-05T17:54:14.000Z","updated_at":"2025-04-01T02:37:05.000Z","dependencies_parsed_at":"2023-01-15T05:42:55.138Z","dependency_job_id":"3916acef-38b6-4822-9eb2-226ffc8c5fb4","html_url":"https://github.com/fastify/fastify-express","commit_stats":{"total_commits":162,"total_committers":21,"mean_commits":7.714285714285714,"dds":0.6358024691358024,"last_synced_commit":"bc482e4cf97607d1a809e3610c5ee184187fbdae"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/fastify-express/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248781394,"owners_count":21160707,"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":["compatibility","express","fastify","fastify-plugin"],"created_at":"2024-08-02T14:00:43.664Z","updated_at":"2025-04-13T20:39:39.993Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# @fastify/express\n\n[![CI](https://github.com/fastify/fastify-express/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/fastify-express/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/@fastify/express.svg?style=flat)](https://www.npmjs.com/package/@fastify/express)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)\n\nThis plugin adds full [Express](http://expressjs.com) compatibility to Fastify, it exposes the same `use` function of Express, and it allows you to use any Express middleware or application.\u003cbr/\u003e\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd rowspan=\"2\"\u003e\u003cb\u003eNote\u003c/b\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cb\u003eThis plugin should not be used as a long-term solution, it aims to help you have a smooth transition from Express to Fastify, but you should migrate your Express specific code to Fastify over time.\u003c/b\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cb\u003eSince \u003ca href=\"https://github.com/expressjs/express/issues/2761\"\u003eExpress does not support Node.js core HTTP/2 module\u003c/a\u003e, this plugin does not support HTTP/2 either.\u003c/b\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003ctbody\u003e\n\u003c/table\u003e\n\n## Install\n```\nnpm i @fastify/express\n```\n\n### Compatibility\n| Plugin version | Fastify version |\n| ---------------|-----------------|\n| `\u003e=4.x`        | `^5.x`          |\n| `\u003e=2.x \u003c4.x`   | `^4.x`          |\n| `^1.x`         | `^3.x`          |\n| `^0.x`         | `^2.x`          |\n\n\nPlease note that if a Fastify version is out of support, then so are the corresponding versions of this plugin\nin the table above.\nSee [Fastify's LTS policy](https://github.com/fastify/fastify/blob/main/docs/Reference/LTS.md) for more details.\n\n## Usage\nRegister the plugin and start using your Express middlewares.\n```js\nconst Fastify = require('fastify')\n\nasync function build () {\n  const fastify = Fastify()\n  await fastify.register(require('@fastify/express'))\n  // do you know we also have cors support?\n  // https://github.com/fastify/fastify-cors\n  fastify.use(require('cors')())\n  // express.Application is also accessible\n  fastify.express.disabled('x-powered-by') // true\n  return fastify\n}\n\nbuild()\n  .then(fastify =\u003e fastify.listen({ port: 3000 }))\n  .catch(console.log)\n```\n\n### Add a complete application\n\nYou can register an entire Express application and make it work with Fastify. Remember, `@fastify/express` is just `express` under the covers and requires the same body parsers as you'd use in `express`.\n\n```js\n// index.js\nconst fastify = require('fastify')()\nconst express = require('express')\nconst router = express.Router()\n\nrouter.use(function (req, res, next) {\n  res.setHeader('x-custom', true)\n  next()\n})\n\nrouter.get('/hello', (req, res) =\u003e {\n  res.status(201)\n  res.json({ hello: 'world' })\n})\n\nrouter.get('/foo', (req, res) =\u003e {\n  res.status(400)\n  res.json({ foo: 'bar' })\n})\n\nrouter.patch('/bar', (req, res) =\u003e {\n  if (!req.body || Object.keys(req.body).length === 0) {\n    res.status(400)\n    res.json({ msg: 'no req.body'})\n  } else {\n    res.status(200)\n    res.json(req.body)\n  }\n})\n\nrouter.use('*', (req, res) =\u003e {\n  res.status(404)\n  res.json({ msg: 'not found'})\n})\n\nfastify.register(require('@fastify/express'))\n  .after(() =\u003e {\n    fastify.use(express.urlencoded({extended: false})) // for Postman x-www-form-urlencoded\n    fastify.use(express.json())\n\n    fastify.use(router)\n  })\n\nfastify.listen({ port: 3000 }, console.log)\n```\n\n#### Testing Your App\nRun `node index.js` to start your server. Then run the following commands to ensure your server is working. Use the optional `-v` flag in curl for verbose output.\n\n```bash\nme@computer ~ % curl -X GET http://localhost:3000/hello\n{\"hello\":\"world\"}%\nme@computer ~ % curl -X GET http://localhost:3000/foo\n{\"foo\":\"bar\"}%\nme@computer ~ % curl -X GET http://localhost:3000/bar\n{\"msg\":\"not found\"}%\nme@computer ~ % curl -X PATCH -H 'content-type:application/json' http://localhost:3000/bar\n{\"msg\":\"no req.body\"}%\nme@computer ~ % curl -X PATCH -H 'content-type:application/json' -d '{\"foo2\":\"bar2\"}' http://localhost:3000/bar\n{\"foo2\":\"bar2\"}%\n```\n\n### Encapsulation support\n\nThe encapsulation works as usual with Fastify, you can register the plugin in a subsystem and your express code will work only inside there, or you can declare the express plugin top level and register a middleware in a nested plugin, and the middleware will be executed only for the nested routes of the specific plugin.\n\n*Register the plugin in its own subsystem:*\n```js\nconst fastify = require('fastify')()\n\nfastify.register(subsystem)\n\nasync function subsystem (fastify, opts) {\n  await fastify.register(require('@fastify/express'))\n  fastify.use(require('cors')())\n}\n```\n\n*Register a middleware in a specific plugin:*\n```js\nconst fastify = require('fastify')()\n\nfastify\n  .register(require('@fastify/express'))\n  .register(subsystem)\n\nasync function subsystem (fastify, opts) {\n  fastify.use(require('cors')())\n}\n```\n\n### Hooks and middleware\n\nEvery registered middleware will be run during the `onRequest` hook phase, so the registration order is important.\nTake a look at the [Lifecycle](https://fastify.dev/docs/latest/Reference/Lifecycle) documentation page to understand better how every request is executed.\n\n```js\nconst fastify = require('fastify')()\n\nfastify\n  .register(require('@fastify/express'))\n  .register(subsystem)\n\nasync function subsystem (fastify, opts) {\n  fastify.addHook('onRequest', async (req, reply) =\u003e {\n    console.log('first')\n  })\n\n  fastify.use((req, res, next) =\u003e {\n    console.log('second')\n    next()\n  })\n\n  fastify.addHook('onRequest', async (req, reply) =\u003e {\n    console.log('third')\n  })\n}\n```\n\n### Restrict middleware execution to a certain path(s)\n\nIf you need to run a middleware only under certain path(s), just pass the path as the first parameter to use and you are done!\n\n```js\nconst fastify = require('fastify')()\nconst path = require('node:path')\nconst serveStatic = require('serve-static')\n\nfastify\n  .register(require('@fastify/express'))\n  .register(subsystem)\n\nasync function subsystem (fastify, opts) {\n  // Single path\n  fastify.use('/css', serveStatic(path.join(__dirname, '/assets')))\n\n  // Wildcard path\n  fastify.use('/css/*', serveStatic(path.join(__dirname, '/assets')))\n\n  // Multiple paths\n  fastify.use(['/css', '/js'], serveStatic(path.join(__dirname, '/assets')))\n}\n```\n\n### Wrap Express req in Proxy\n\nIt is possible to wrap the Express request object in a Proxy by passing `createProxyHandler` function to generate the Proxy handler. The function will receive the Fastify request object as the first parameter.\n\nFor example, using Proxy to expose something from Fastify request into the Express request.\n\n```js\nfastify.decorateRequest('welcomeMessage', 'Hello World');\nfastify.register(expressPlugin, {\n  createProxyHandler: fastifyRequest =\u003e ({\n    get (target, prop) {\n      if (prop === 'welcomeMessage') {\n        return fastifyRequest[prop]\n      }\n\n      return target[prop]\n    }\n  })\n})\n```\n\n## TypeScript support\n\nTo use this module with TypeScript, make sure to install `@types/express`.\n\nYou will need to add `\"types\": [\"@fastify/express\"]` to your tsconfig.json file when using `require` to import the plugin.\n\n## Middleware alternatives\n\nFastify offers some alternatives to the most commonly used middleware:\n\n| Express Middleware | Fastify Plugin |\n| ------------- |---------------|\n| [`helmet`](https://github.com/helmetjs/helmet) | [`@fastify/helmet`](https://github.com/fastify/fastify-helmet) |\n| [`cors`](https://github.com/expressjs/cors) | [`@fastify/cors`](https://github.com/fastify/fastify-cors) |\n| [`serve-static`](https://github.com/expressjs/serve-static) | [`@fastify/static`](https://github.com/fastify/fastify-static) |\n\n## Troubleshooting\n\n### POST request with body hangs up\n\n[body-parser](https://github.com/expressjs/body-parser) library incompatible with `fastify-express`, when you have `fastify` routes and any `express` middlewares.\nAny POST requests with **body**, which `body-parser` will try to parse, will hang up.\n\nExample application:\n\n```js\nconst Fastify = require('fastify')\nconst Express = require('express')\nconst expressPlugin = require('@fastify/express')\nconst bodyParser = require('body-parser')\n\nconst fastify = Fastify()\nconst express = Express()\n\nexpress.use(bodyParser.urlencoded({ extended: false }))\n\nawait fastify.register(expressPlugin)\n\nfastify.use(express)\n\n// this route will never reply\nfastify.post('/hello', (req, reply) =\u003e {\n  return { hello: 'world' }\n})\n```\n\nFor this case, you need to remove `body-parser`, install `@fastify/formbody` and change `@fastify/express` options:\n\n\n```js\nconst Fastify = require('fastify')\nconst Express = require('express')\nconst expressPlugin = require('@fastify/express')\nconst fastifyFormBody = require('@fastify/formbody')\n\nconst fastify = Fastify()\nconst express = Express()\n\nawait fastify.register(fastifyFormBody)\nawait fastify.register(expressPlugin, {\n  // run express after `@fastify/formbody` logic\n  expressHook: 'preHandler'\n})\n\nfastify.use(express)\n\n// it works!\nfastify.post('/hello', (req, reply) =\u003e {\n  return { hello: 'world' }\n})\n```\n\n## License\n\nLicensed under [MIT](./LICENSE).\u003cbr/\u003e\n[`express` license](https://github.com/expressjs/express/blob/master/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-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Ffastify-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Ffastify-express/lists"}