Overview
CORS controls which websites can call your API from a browser. Without proper CORS headers, browsers block cross-origin requests. Misconfigured CORS is either too restrictive (breaks your frontend) or too permissive (security risk). This skill covers correct configuration for common setups.
Instructions
Step 1: Express
// server.ts — CORS configuration for Express
import cors from 'cors'
import express from 'express'
const app = express()
// Production: whitelist specific origins
const allowedOrigins = [
'https://myapp.com',
'https://admin.myapp.com',
process.env.NODE_ENV === 'development' && 'http://localhost:3000',
].filter(Boolean) as string[]
app.use(cors({
origin: (origin, callback) => {
// Allow requests with no origin (mobile apps, curl, server-to-server)
if (!origin) return callback(null, true)
if (allowedOrigins.includes(origin)) return callback(null, true)
callback(new Error(`Origin ${origin} not allowed by CORS`))
},
credentials: true, // allow cookies/auth headers
methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
allowedHeaders: ['Content-Type', 'Authorization'],
maxAge: 86400, // cache preflight for 24h
}))
Step 2: Next.js API Routes
// next.config.ts — CORS via Next.js headers
const nextConfig = {
async headers() {
return [
{
source: '/api/:path*',
headers: [
{ key: 'Access-Control-Allow-Origin', value: 'https://myapp.com' },
{ key: 'Access-Control-Allow-Methods', value: 'GET,POST,PUT,DELETE,OPTIONS' },
{ key: 'Access-Control-Allow-Headers', value: 'Content-Type, Authorization' },
{ key: 'Access-Control-Allow-Credentials', value: 'true' },
{ key: 'Access-Control-Max-Age', value: '86400' },
],
},
]
},
}
Step 3: Manual Headers (Any Framework)
// middleware.ts — Manual CORS for any HTTP server
export function corsMiddleware(req, res, next) {
const origin = req.headers.origin
const allowed = ['https://myapp.com', 'https://admin.myapp.com']
if (allowed.includes(origin)) {
res.setHeader('Access-Control-Allow-Origin', origin)
res.setHeader('Access-Control-Allow-Credentials', 'true')
}
// Handle preflight (OPTIONS) requests
if (req.method === 'OPTIONS') {
res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE')
res.setHeader('Access-Control-Allow-Headers', 'Content-Type,Authorization')
res.setHeader('Access-Control-Max-Age', '86400')
return res.status(204).end()
}
next()
}
Examples
Example 1: "Our React app on app.billing-portal.io gets blocked calling our Express API"
Add the Express middleware from Step 1 with app.billing-portal.io in allowedOrigins, keep credentials: true since the app sends an auth cookie, and confirm the browser's preflight OPTIONS request now returns 204 with the right Access-Control-Allow-* headers (check the Network tab, not just the follow-up GET/POST).
Example 2: "A Next.js API route works in Postman but not from the browser"
Postman does not send an Origin header, so it skips CORS entirely — that it works there proves nothing about the browser case. Use the next.config.ts headers() block from Step 2 if one static origin is always correct; headers() values are fixed per build, like vercel.json, so if the allowed origin needs to vary per request (a whitelist, a wildcard subdomain), set the headers in middleware instead, mirroring Step 3.
Guidelines
- NEVER use
Access-Control-Allow-Origin: *withcredentials: true— browsers reject this combination outright. *origin is only safe for truly public APIs with no authentication and no cookies.- Always set
Access-Control-Max-Ageto cache preflight responses (reduces repeatOPTIONSrequests). - CORS is enforced by the browser, not the server — server-to-server calls, curl and Postman ignore it, so testing from those tools cannot confirm a browser-facing fix.
- If using cookies across domains, also set
SameSite=None; Secureon the cookie, andcredentials: true/Access-Control-Allow-Credentials: trueon both sides. next.config.js/next.config.tsheaders()values are static at build time; use middleware when the allowed origin must be computed per request.