---

name: cors description: >- Configure CORS for web APIs. Use when a user asks to fix CORS errors, allow cross-origin requests, configure CORS headers, handle preflight requests, or secure API access from different domains. license: Apache-2.0 compatibility: 'Express, Fastify, Next.js, any HTTP server' metadata: author: terminal-skills version: 1.1.0 category: devops tags: - cors - security - headers - api - browser

CORS (Cross-Origin Resource Sharing)

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: * with credentials: 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-Age to cache preflight responses (reduces repeat OPTIONS requests).
• 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; Secure on the cookie, and credentials: true/Access-Control-Allow-Credentials: true on both sides.
• next.config.js/next.config.ts headers() values are static at build time; use middleware when the allowed origin must be computed per request.