> For the complete documentation index, see [llms.txt](https://marblejs.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://marblejs.gitbook.io/docs/other/api-reference/middleware-cors.md).

# @marblejs/middleware-cors

### Installation

```bash
yarn add @marblejs/middleware-cors
```

Requires `@marblejs/core` to be installed.

### Importing

```typescript
import { cors$ } from '@marblejs/middleware-cors';
```

### Type declaration <a href="#type-declaration" id="type-declaration"></a>

```
cors$ :: CORSOptions -> HttpMiddlewareEffect
```

### Parameters

| parameter | definition                |
| --------- | ------------------------- |
| *options* | \<optional> `CORSOptions` |

***CORSOptions***

| ***parameter***      | definition                                 |
| -------------------- | ------------------------------------------ |
| origin               | \<optional> `string \| string[] \| RegExp` |
| methods              | \<optional> `HttpMethod[]`                 |
| optionsSuccessStatus | \<optional> `HttpStatus`                   |
| allowHeaders         | \<optional> `string \| string[]`           |
| exposeHeaders        | \<optional> `string[]`                     |
| withCredentials      | \<optional> `boolean`                      |
| maxAge               | \<optional> `number`                       |

This object allows you to configure CORS headers with various options. Both `methods` and `exposeHeaders` support wildcard. By default options are configured as following.

```typescript
{ 
  origin: '*',
  methods: ['HEAD', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
  withCredentials: false,
  optionsSuccessStatus: HttpStatus.NO_CONTENT, // 204
}
```

Note that provided options are merged with default options so you need to overwrite each default parameter you want to customize.

### Basic usage

```typescript
import { httpListener } from '@marblejs/core';
import { cors$ } from '@marblejs/middleware-cors';

export const listener = httpListener({
  middlewares: [
    cors$({
      origin: '*',
      allowHeaders: '*',
      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
    })
  ],
  effects: [/* ... */],
});
```

For security purpose it's better to be strict as possible when configuring CORS options.

### Strict usage

```typescript
import { httpListener } from '@marblejs/core';
import { cors$ } from '@marblejs/middleware-cors';

export const listener = httpListener({
  middlewares: [
    cors$({
      origin: ['http://example1.com', 'http://example2.com'],
      allowHeaders: ['Origin', 'Authorization', 'Content-Type'],
      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
    })
  ],
  effects: [/* ... */],
});
```

Headers notation is case insensitive. `content-type` will also work.