nextjs-cors

2.2.1 verified Sat Apr 25 auth: no javascript

CORS middleware for Next.js API routes, built on top of the popular Express cors package. Current stable version is 2.2.1, released as a patch update preparing for the next major version. Provides a simple, drop-in solution to enable Cross-Origin Resource Sharing in Next.js API routes with all standard cors options (methods, origin, allowed headers, etc.). Uses an async middleware pattern that fits naturally into Next.js API route handlers. Unlike generic cors packages, nextjs-cors is specifically designed for Next.js's request/response model and does not require wrapping or additional configuration to work with Edge Runtime (though support depends on underlying cors). Ships TypeScript definitions, making it easy to use in TS projects. Peer dependency on Next.js >=8.1.1-canary.54, ensuring compatibility with older versions. Compared to other Next.js CORS solutions like next-connect or manual headers, nextjs-cors offers a minimal API and leverages the well-tested cors package.

Common errors

error TypeError: NextCors is not a function ↓

cause Using named import instead of default import, or using require without .default in ESM-mode module resolution.

fix

Use import NextCors from 'nextjs-cors' or const NextCors = require('nextjs-cors').default;

error Error: Cannot find module 'nextjs-cors' ↓

cause Package not installed, or installed in wrong environment (e.g., missing from dependencies).

fix

Run npm install nextjs-cors --save or yarn add nextjs-cors.

error CORS request failed with status 500: "Cannot set headers after they are sent to the client" ↓

cause NextCors is called after response has already been sent or multiple calls to NextCors occur.

fix

Ensure NextCors is called early in the handler, and do not call res.end() before it.

Warnings

breaking Requires Next.js >=8.1.1-canary.54. Older versions may not support the async handler pattern used. ↓

fix Upgrade Next.js to at least 8.1.1-canary.54 or use an older version of nextjs-cors.

deprecated OptionsSuccessStatus option: using it defaults to 200 but modern browsers expect 204. Consider omitting or setting to 204. ↓

fix Remove optionsSuccessStatus or set to 204: optionsSuccessStatus: 204

gotcha The underlying cors package's origin option might not work as expected with wildcard '*' when credentials are required. Must explicitly set origin for credentialed requests. ↓

fix Set origin to a specific domain instead of '*' when using credentials: true.

gotcha Importing with CommonJS require requires .default access. ↓

fix Use const NextCors = require('nextjs-cors').default;

gotcha If using TypeScript and you see 'Could not find a declaration file for module', ensure types are installed (they are bundled, but tsconfig may need to be configured). ↓

fix Check that your tsconfig includes 'node_modules/@types' or set 'moduleResolution': 'node'.

Install

npm install nextjs-cors

yarn add nextjs-cors

pnpm add nextjs-cors

Imports

NextCors
wrong
```
const NextCors = require('nextjs-cors')
```
correct
```
import NextCors from 'nextjs-cors'
```
Package is ESM-only. Default export is a function; do not use named import.
NextCors
wrong
```
import { NextCors } from 'nextjs-cors'
```
correct
```
import NextCors from 'nextjs-cors'
```
Named import is incorrect; the package uses a default export.

require

wrong

const NextCors = require('nextjs-cors')

correct

const NextCors = require('nextjs-cors').default

In CommonJS, you must access .default due to ESM default export.

Quickstart

Demonstrates how to use nextjs-cors as middleware in a Next.js API route with CORS options.

import NextCors from 'nextjs-cors';
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  await NextCors(req, res, {
    methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
    origin: '*',
    optionsSuccessStatus: 200,
  });

  res.json({ message: 'Hello NextJs Cors!' });
}