CORS

This guide covers Cross-Origin Resource Sharing (CORS) in AdonisJS applications. You will learn how to:

• Install and configure the CORS middleware
• Control which origins, methods, and headers are allowed
• Handle credentials in cross-origin requests
• Debug common CORS errors

Overview

When a browser makes a request to a different domain than the one serving the current page, it enforces Cross-Origin Resource Sharing (CORS) restrictions. This security mechanism prevents malicious scripts from making unauthorized requests to your API on behalf of users.

For example, if your frontend runs on app.example.com and your API runs on api.example.com, the browser will block requests from the frontend unless your API explicitly allows that origin. The same applies during local development when your frontend runs on localhost:3000 and your API on localhost:3333.

Before making certain cross-origin requests, browsers send a preflight request using the OPTIONS HTTP method. This preflight asks your server which origins, methods, and headers are permitted. Your server must respond with the appropriate CORS headers, and only then will the browser proceed with the actual request.

AdonisJS handles CORS through the @adonisjs/cors package, which provides middleware that automatically responds to preflight requests and attaches the correct headers to all responses.

Installation

Install and configure the package using the following command:

node ace add @adonisjs/cors

Configuration

The CORS configuration lives in config/cors.ts. Here is the default configuration with all available options:

import { defineConfig } from '@adonisjs/cors'

const corsConfig = defineConfig({
  enabled: true,
  origin: true,
  methods: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE'],
  headers: true,
  exposeHeaders: [],
  credentials: true,
  maxAge: 90,
})

export default corsConfig

Enabling and disabling CORS

The enabled option turns the middleware on or off without removing it from the middleware stack. This is useful when you want to disable CORS temporarily during debugging or in specific environments.

{
  enabled: process.env.NODE_ENV !== 'test'
}

Configuring allowed origins

The origin option controls which domains can make cross-origin requests to your API. This sets the Access-Control-Allow-Origin response header.

To allow all origins dynamically (the response header will mirror the requesting origin):

{
  origin: true
}

To disallow all cross-origin requests:

{
  origin: false
}

To allow specific domains, provide an array of origins:

{
  origin: ['https://app.example.com', 'https://admin.example.com']
}

To allow any origin using the wildcard:

{
  origin: '*'
}

For dynamic origin validation, provide a callback function. This is useful when allowed origins are stored in a database or when you need custom validation logic:

{
  origin: (requestOrigin, ctx) => {
    /**
     * requestOrigin is the value of the Origin header.
     * Return true to allow, false to deny.
     */
    const allowedOrigins = ['https://app.example.com']
    return allowedOrigins.includes(requestOrigin)
  }
}

Configuring allowed methods

The methods option specifies which HTTP methods are permitted for cross-origin requests. The browser's preflight request includes an Access-Control-Request-Method header, and the server checks this value against the allowed methods.

{
  methods: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE']
}

Configuring allowed headers

The headers option controls which request headers are permitted in cross-origin requests. The browser's preflight request includes an Access-Control-Request-Headers header listing the headers the client wants to send.

To allow all headers:

{
  headers: true
}

To allow specific headers:

{
  headers: ['Content-Type', 'Accept', 'Authorization']
}

For dynamic header validation, provide a callback:

{
  headers: (requestHeaders, ctx) => {
    return true
  }
}

Exposing response headers

By default, browsers only expose a limited set of response headers to JavaScript. The exposeHeaders option lets you specify additional headers that should be accessible to the client.

{
  exposeHeaders: ['X-Request-Id', 'X-RateLimit-Remaining']
}

Allowing credentials

The credentials option controls whether cookies, authorization headers, and TLS client certificates can be included in cross-origin requests. When enabled, the server sends the Access-Control-Allow-Credentials: true header.

{
  credentials: true
}

Caching preflight responses

The maxAge option specifies how long (in seconds) browsers should cache preflight responses. This reduces the number of preflight requests for repeated cross-origin calls.

{
  maxAge: 90
}

Setting maxAge to null omits the Access-Control-Max-Age header entirely. Setting it to -1 sends the header but disables caching.

Common scenarios

API serving a single-page application

When your API and frontend are deployed on different domains, configure CORS to allow your frontend's origin with credentials:

import { defineConfig } from '@adonisjs/cors'

const corsConfig = defineConfig({
  enabled: true,
  origin: ['https://app.example.com'],
  methods: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE'],
  headers: true,
  credentials: true,
  maxAge: 90,
})

export default corsConfig

Local development with different ports

During development, your frontend and backend often run on different ports. Configure CORS to allow your local frontend origin:

import { defineConfig } from '@adonisjs/cors'

const corsConfig = defineConfig({
  enabled: true,
  origin: (requestOrigin) => {
    /**
     * Allow localhost on any port during development.
     */
    return requestOrigin.startsWith('http://localhost')
  },
  methods: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE'],
  headers: true,
  credentials: true,
  maxAge: 90,
})

export default corsConfig

Public API with no credentials

If your API is public and does not require cookies or authentication headers, you can use a permissive configuration:

import { defineConfig } from '@adonisjs/cors'

const corsConfig = defineConfig({
  enabled: true,
  origin: '*',
  methods: ['GET', 'HEAD', 'POST'],
  headers: true,
  credentials: false,
  maxAge: 86400,
})

export default corsConfig

See also

• MDN CORS documentation for an in-depth explanation of how CORS works
• Middleware to learn about the AdonisJS middleware system
• Session for handling cookies in cross-origin requests