CORS plugin

This plugin adds support for customizing Cross-Origin Resource Sharing behavior.

Install with:

bun add @elysia/cors@next

Then use it:

import { Elysia } from 'elysia'
import { cors } from '@elysia/cors'

new Elysia().use(cors()).listen(3000)

This will set Elysia to accept requests from any origin.

Config

Below is the config that is accepted by the plugin

origin

Default: true

Indicates whether the response can be shared with the requesting code from the given origins.

Value can be one of the following:

string - Origin compared against the request’s Origin header (the scheme is optional, eg: 'example.com'); on a match, the request’s origin is echoed in the Access-Control-Allow-Origin header, otherwise the header is omitted. '*' allows any origin.
boolean - true accepts any origin and reflects the request’s Origin header, falling back to * when absent. false disables the allow-origin header.
RegExp - Pattern matched against the request’s Origin header; allowed if matched.
Function - Custom logic to allow resource sharing. Allow it if true is returned.
- Expected to have the type of:
```
type OriginCheck = (request: Request) => boolean | void
```
Array<string | RegExp | Function> - iterate through all cases above in order, allowed if any of the values are true.

methods

Default: true

Allowed methods for cross-origin requests. The default true reflects the method requested by a preflight. Set false to omit this header.

Assign the Access-Control-Allow-Methods header.

Value can be one of the following:

false | null | ” - Omit the allow-methods header. Leaving the option undefined uses the default.
* - Allows all methods.
string - Expects either a single method or a comma-delimited string
- (eg: 'GET, PUT, POST')
string[] - Allow multiple HTTP methods.
- eg: ['GET', 'PUT', 'POST']

allowedHeaders

Default: true

Allowed headers for an incoming request. The default true reflects Access-Control-Request-Headers on preflight requests.

Assign the Access-Control-Allow-Headers header.

Value can be one of the following:

string - Expects either a single header or a comma-delimited string
- eg: 'Content-Type, Authorization'.
string[] - Allow multiple HTTP headers.
- eg: ['Content-Type', 'Authorization']

exposeHeaders

Default: true

Expose the specified headers to browser JavaScript. The default true reflects the incoming request’s header names on every response, preflight included; provide a string or array to choose explicit names.

Assign the Access-Control-Expose-Headers header.

Value can be one of the following:

string - Expects either a single header or a comma-delimited string.
- eg: 'Content-Type, X-Powered-By'.
string[] - Allow multiple HTTP headers.
- eg: ['Content-Type', 'X-Powered-By']

credentials

Default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode Request.credentials is include.

When a request’s credentials mode Request.credentials is include, browsers will only expose the response to the frontend JavaScript code if the Access-Control-Allow-Credentials value is true.

Credentials are cookies, authorization headers, or TLS client certificates.

Assign the Access-Control-Allow-Credentials header.

maxAge

Default: 5

Indicates how long the results of a preflight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.

Assign the Access-Control-Max-Age header.

preflight

Default: true

The preflight request is a request sent to check if the CORS protocol is understood and if a server is aware of using specific methods and headers.

It is sent as an OPTIONS request with 3 HTTP request headers:

Access-Control-Request-Method
Access-Control-Request-Headers
Origin

This config indicates if the server should respond to preflight requests.

Pattern

Below you can find the common patterns to use the plugin.

Allow CORS by domain

import { Elysia } from 'elysia'
import { cors } from '@elysia/cors'

const app = new Elysia()
  .use(
    cors({
      origin: /^https:\/\/(?:[a-z0-9-]+\.)*saltyaom\.com$/i
    })
  )
  .get('/', () => 'Hi')
  .listen(3000)

This allows HTTPS origins at saltyaom.com and its subdomains. The anchors keep unrelated hostnames from matching.