@fastify/cors

If you need to determine CORS settings dynamically based on the request, you can configure CORS asynchronously. You can do this by passing a callback to fastify.register or by using the delegator key in the options object.

// Method 1: Using a callback in register
fastify.register(require('@fastify/cors'), (instance) => {
  return (req, callback) => {
    const corsOptions = {
      origin: true
    };

    if (/^localhost$/m.test(req.headers.origin)) {
      corsOptions.origin = false
    }

    callback(null, corsOptions)
  }
})

// Method 2: Using the delegator key in options
fastify.register(require('@fastify/cors'), {
  hook: 'preHandler',
  delegator: (req, callback) => {
    const corsOptions = {
      origin: true
    };

    if (/^localhost$/m.test(req.headers.origin)) {
      corsOptions.origin = false
    }

    callback(null, corsOptions)
  },
})

To use @fastify/cors, import the plugin and register it with your Fastify instance. You can pass an options object or use the default settings.

import Fastify from 'fastify'
import cors from '@fastify/cors'

const fastify = Fastify()
await fastify.register(cors, {
  // put your options here
})

fastify.get('/', (req, reply) => {
  reply.send({ hello: 'world' })
})

await fastify.listen({ port: 3000 })

Install the @fastify/cors plugin using npm to enable Cross-Origin Resource Sharing in your Fastify application.

npm i @fastify/cors

You can override the global CORS plugin options for specific routes using the config.cors property in the route definition.

fastify.register(require('@fastify/cors'), { origin: 'https://example.com' })

// Route with custom origin (Allow all)
fastify.get('/cors-allow-all', {
  config: {
    cors: {
      origin: '*', 
    },
  },
}, (_req, reply) => {
  reply.send('Custom CORS headers applied')
})

// Route with CORS disabled
fastify.get('/cors-disabled', {
  config: {
    cors: false,
  },
}, (_req, reply) => {
  reply.send('No CORS headers')
})

If you need to determine CORS settings dynamically (e.g., checking a database or a whitelist for each request), you can use a delegator function in the options object. The delegator can be a standard callback-style function or a function that returns a Promise.

Callback style: delegator: (req, callback) => callback(null, 'https://allowed-origin.com')

Promise style: delegator: (req) => Promise.resolve('https://allowed-origin.com')

fastify.register(cors, {
  delegator: (req, next) => {
    const origin = req.headers.origin
    if (isAllowed(origin)) {
      next(null, origin)
    } else {
      next(new Error('Not allowed'))
    }
  }
})

The plugin automatically handles OPTIONS preflight requests.

1. It registers an OPTIONS * route to intercept preflight requests before other plugins (like authentication) can deny them.
2. If preflight: true (default) and strictPreflight: true (default), the plugin validates that the request contains the required origin and access-control-request-method headers, returning a 400 if they are missing.
3. If preflightContinue is false (default), the plugin sends a response immediately (e.g., 204 No Content) and terminates the request lifecycle for that preflight. If true, it allows the request to proceed to subsequent hooks.

To enable CORS in your Fastify application, register the @fastify/cors plugin. You can pass a configuration object or a delegator function to dynamically resolve CORS options based on the request.

const fastify = require('fastify')()
const cors = require('@fastify/cors')

fastify.register(cors, {
  origin: 'https://example.com',
  methods: 'GET,HEAD,POST'
})

By default, @fastify/cors uses the onRequest hook. You can change this to any valid Fastify hook name to control when CORS validation and header injection occur.

import Fastify from 'fastify'
import cors from '@fastify/cors'

const fastify = Fastify()
await fastify.register(cors, {
  hook: 'preHandler',
})

fastify.get('/', (req, reply) => {
  reply.send({ hello: 'world' })
})

Ensure your Fastify version is compatible with the @fastify/cors version you are installing:

You can override the global CORS configuration for individual routes by using the config.cors key in the route definition. Setting cors: false will disable CORS for that specific route.

// Disable CORS for this specific route
fastify.get('/no-cors', {
  config: {
    cors: false
  }
}, async (request, reply) => {
  return { hello: 'world' }
})

// Override with specific options
fastify.get('/custom-cors', {
  config: {
    cors: {
      origin: 'https://specific-origin.com'
    }
  }
}, async (request, reply) => {
  return { hello: 'world' }
})