---
title: CORS Handler
description: Set rules for Cross Origin Resource Sharing.
links:
  - label: Enabled
    icon: i-heroicons-check-badge
    color: green
    size: xs
---

This middleware will help you set your CORS options and it is based on built in [H3 CORS](https://github.com/unjs/h3) functionality

::callout{icon="i-heroicons-light-bulb"}
 Read more about Cross Origin Resource Sharing [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
::

Testing CORS configuration can be done by running one application with NuxtSecurity enabled and creating a second application (that is running on a different port) that will send a request to the first app. Then, a CORS error could be easily observed that proves that CORS is working as expected.

## Usage

This middleware is enabled globally by default. You can customize it both globally and per route like following:

```js{}[nuxt.config.ts]
export default defineNuxtConfig({

  // Global
  security: {
    corsHandler: {
      // options
    }
  }

  // Per Route
  routeRules: {
    '/my-secret-route': {
      security: {
        corsHandler: {
          // options
        }
      }
    }
  }
})
```

You can also disable the middleware globally or per route by setting `corsHandler: false`.

## Options

CORS handler accepts following configuration options:

```ts
interface CorsOptions = {
  origin?: '*' | string | string[];
  useRegExp?: boolean;
  methods?: '*' | HTTPMethod[];
  allowHeaders?: '*' | string[];
  exposeHeaders?: '*' | string[];
  credentials?: boolean;
  maxAge?: string | false;
  preflight?: {
      statusCode?: number;
  };
}
```

### `origin`

- Default: `${serverUrl}`

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. Use `'*'` to allow all origins. You can pass a single origin, or a list of origins.

### `useRegExp`

Set to `true` to parse all origin values into a regular expression using `new RegExp(origin, 'i')`.
You cannot use RegExp instances directly as origin values, because the nuxt config needs to be serializable.
When using regular expressions, make sure to escape dots in origins correctly. Otherwise a dot will match every character.

The following matches `https://1.foo.example.com`, `https://a.b.c.foo.example.com`, but not `https://foo.example.com`.
`'(.*)\\.foo.example\\.com'`

### `methods`

- Default: `['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']`

The Access-Control-Allow-Methods response header specifies one or more methods allowed when accessing a resource in response to a preflight request.

### `allowHeaders`

- Default: `-`

The Access-Control-Allow-Headers response header is used in response to a preflight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.

### `exposeHeaders`

- Default: `-`

The Access-Control-Expose-Headers response header allows a server to indicate which response headers should be made available to scripts running in the browser, in response to a cross-origin request.

### `credentials`

- Default: `-`

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.

### `maxAge`

- Default: `-`

The Access-Control-Max-Age response header 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.

### `preflight.statusCode`

- Default: `204`

Status code for preflight request.