@fastify/express

The plugin respects Fastify's encapsulation model. You can:

1. Register the plugin in a subsystem: Express middleware will only be available within that specific plugin scope.
2. Register middleware in a nested plugin: If @fastify/express is registered at the top level, middleware registered inside a nested plugin will only execute for routes within that plugin's scope.

// Example: Registering middleware in a specific plugin scope
const fastify = require('fastify')()

fastify
  .register(require('@fastify/express'))
  .register(subsystem)

async function subsystem (fastify, opts) {
  // This middleware only applies to routes inside 'subsystem'
  fastify.use(require('cors')())
}

Every registered Express middleware runs during the Fastify onRequest hook phase. When mixing Fastify hooks and Express middleware, the order of registration determines the execution order. In the example below, the Fastify onRequest hook runs before the Express middleware.

const fastify = require('fastify')()

fastify
  .register(require('@fastify/express'))
  .register(subsystem)

async function subsystem (fastify, opts) {
  fastify.addHook('onRequest', async (req, reply) => {
    console.log('first')
  })

  fastify.use((req, res, next) => {
    console.log('second')
    next()
  })

  fastify.addHook('onRequest', async (req, reply) => {
    console.log('third')
  })
}

You can register an entire Express Router or application instance. Because @fastify/express is Express under the hood, you must manually register Express body parsers (like express.json() or express.urlencoded()) if your Express routes depend on them.

// index.js
const fastify = require('fastify')()
const express = require('express')
const router = express.Router()

router.get('/hello', (req, res) => {
  res.status(201)
  res.json({ hello: 'world' })
})

fastify.register(require('@fastify/express'))
  .after(() => {
    // Register body parsers required by Express
    fastify.use(express.urlencoded({extended: false}))
    fastify.use(express.json())

    fastify.use(router)
  })

fastify.listen({ port: 3000 }, console.log)

Install the plugin using npm to add Express compatibility to your Fastify application.

npm i @fastify/express

To use @fastify/express with TypeScript:

1. Install @types/express.
2. If using require to import the plugin, add "types": ["@fastify/express"] to your tsconfig.json.

To enable Express middleware compatibility in your Fastify application, register the @fastify/express plugin. This plugin adds the .use() method to your Fastify instance, allowing you to use standard Express middleware.

const fastify = require('fastify')
const fastifyExpress = require('@fastify/express')

const server = fastify({ logger: true })

server.register(fastifyExpress)

server.listen({ port: 3000 })

Register the @fastify/express plugin to gain access to the fastify.use() method, which allows you to use any Express middleware. You can also access fastify.express to interact with the underlying Express application (e.g., disabling features like x-powered-by).

const Fastify = require('fastify')

async function build () {
  const fastify = Fastify()
  await fastify.register(require('@fastify/express'))
  // use express middleware
  fastify.use(require('cors')())
  // access express application settings
  fastify.express.disabled('x-powered-by') // true
  return fastify
}

build()
  .then(fastify => fastify.listen({ port: 3000 }))
  .catch(console.log)

You can wrap the Express req object in a Proxy to expose properties from the Fastify request object to the Express middleware. This is done by providing a createProxyHandler function in the plugin options. The function receives the Fastify request object as its argument.

fastify.decorateRequest('welcomeMessage', 'Hello World');
fastify.register(require('@fastify/express'), {
  createProxyHandler: fastifyRequest => ({
    get (target, prop) {
      if (prop === 'welcomeMessage') {
        return fastifyRequest[prop]
      }
      return target[prop]
    }
  })
})