Cors Configuration

How to configure CORS (Cross-Origin Resource Sharing) correctly so your frontend can talk to your backend without browser blocks, while not leaving your API open to every website on the internet. Use this skill whenever the user mentions CORS, gets a CORS error in the browser, is setting up a frontend and backend on different domains or ports, asks why their API calls are being blocked, or is connecting a Vercel frontend to a Railway/Render backend. Also trigger for phrases like "CORS error", "blocked by CORS policy", "Access-Control-Allow-Origin", "cross-origin", "my frontend can't call my backend", "allow origin star", "credentials mode", "preflight", or any time a frontend on one domain (or localhost port) is calling an API on a different domain or port. Always apply correct CORS config before any backend is deployed — AI gets this wrong constantly, either blocking legitimate requests or opening the API to everyone.CORS Configuration Skill What CORS Actually Is When your frontend (on writingplanner.com) makes a request to your backend (on api.writingplanner.com), the browser asks the backend: "is this frontend allowed to talk to you?" This check is CORS — Cross-Origin Resource Sharing. "Origin" means domain + protocol + port. These are all different origins:

https://writingplanner.com http://writingplanner.com (different protocol) https://api.writingplanner.com (different subdomain) https://writingplanner.com:3001 (different port) http://localhost:3000 (local development)

The browser enforces this. You cannot turn it off on the client side. You configure it on the server.

The Dangerous AI Mistake: Access-Control-Allow-Origin: * This is the most important thing in this skill. Read it twice. When AI can't figure out CORS, it does this: javascript// AI's lazy fix — DO NOT USE THIS app.use((req, res, next) => { res.setHeader('Access-Control-Allow-Origin', '*') next() }) The * wildcard means: any website on the internet can make requests to your API. This seems harmless until you understand the attack: a malicious site evil.com can make requests to api.yourapp.com and the browser will include your users' cookies in those requests. This is called CSRF (Cross-Site Request Forgery). Your API happily processes those requests thinking they came from your app — because the user's auth cookie is included. Never use * on any API that uses cookies for authentication. The only safe use of * is for truly public, read-only APIs with no authentication.

The Correct CORS Setup Installation bashnpm install cors Basic Configuration (Most Common Setup) javascript// config/cors.js const cors = require('cors')

const allowedOrigins = { development: [ 'http://localhost:3000', // React dev server 'http://localhost:5173', // Vite dev server 'http://localhost:4000', // another local port ], staging: [ 'https://staging.writingplanner.com', 'https://writingplanner-staging.vercel.app' ], production: [ 'https://writingplanner.com', 'https://www.writingplanner.com', 'https://app.writingplanner.com' ] }

const corsOptions = { origin: function(origin, callback) { // allow requests with no origin (Postman, curl, server-to-server calls) if (!origin) return callback(null, true)

const env = process.env.NODE_ENV || 'development'
const allowed = allowedOrigins[env] || allowedOrigins.development

if (allowed.includes(origin)) {
  callback(null, true)
} else {
  callback(new Error(`CORS policy: origin ${origin} not allowed`))
}

},

credentials: true, // REQUIRED if you use cookies for auth (httpOnly cookies)

methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],

allowedHeaders: [ 'Content-Type', 'Authorization', 'X-Requested-With' ],

maxAge: 86400 // cache preflight response for 24 hours (reduces preflight requests) }

module.exports = cors(corsOptions) javascript// app.js — apply CORS before ALL other middleware const corsMiddleware = require('./config/cors')

app.use(corsMiddleware) // must be FIRST app.options('*', corsMiddleware) // handle preflight for all routes

app.use(express.json()) app.use('/api/v1', routes) // ... rest of your app

The credentials: true Rule If your frontend sends cookies (which it does when you use httpOnly cookies for auth), you must set credentials: true on the backend AND send credentials from the frontend. Backend: javascriptcorsOptions = { origin: 'https://writingplanner.com', // must be specific URL, NOT * credentials: true // required for cookies } Frontend (fetch): javascriptconst res = await fetch('https://api.writingplanner.com/projects', { credentials: 'include' // send cookies with request }) Frontend (axios): javascriptconst api = axios.create({ baseURL: 'https://api.writingplanner.com', withCredentials: true // send cookies with every request }) Critical rule: When credentials: true, the origin CANNOT be *. It must be an explicit domain. The browser rejects * + credentials as a security measure. If AI sets * and you use cookies, auth will silently stop working.

What Preflight Requests Are For certain requests (POST with JSON body, custom headers, PUT, PATCH, DELETE), the browser sends an OPTIONS request first to ask the server "can I do this?" This is called a preflight check. Your server must respond correctly to OPTIONS requests or the actual request never happens. javascript// app.js — handle preflight explicitly before routes app.options('*', corsMiddleware) // respond to all OPTIONS requests app.use(corsMiddleware) If your API returns 404 for OPTIONS requests, you'll see CORS errors even though your CORS config looks correct — because the preflight is failing.

Environment-Based Origins The cleanest approach: pull allowed origins from environment variables so you don't have to change code for different environments. javascript// config/cors.js const corsOptions = { origin: function(origin, callback) { if (!origin) return callback(null, true)

// comma-separated list of allowed origins in env var
// e.g. ALLOWED_ORIGINS=https://writingplanner.com,https://www.writingplanner.com
const allowed = (process.env.ALLOWED_ORIGINS || 'http://localhost:3000')
  .split(',')
  .map(o => o.trim())

if (allowed.includes(origin)) {
  callback(null, true)
} else {
  callback(new Error(`Origin ${origin} not allowed by CORS`))
}

}, credentials: true, methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'], allowedHeaders: ['Content-Type', 'Authorization'] } bash# .env (local) ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

production environment variable

ALLOWED_ORIGINS=https://writingplanner.com,https://www.writingplanner.com Now your CORS is controlled entirely by an environment variable — no code changes when you add a new frontend domain.

Common CORS Blunders AI Makes Blunder 1: * with cookies javascript// AI's broken version — cookies never work app.use(cors({ origin: '', credentials: true })) // Browser ignores credentials: true when origin is * // httpOnly cookies silently fail to send // Users appear logged out on every request Blunder 2: Missing OPTIONS handler javascript// Missing this line means preflight requests get 404 app.options('', corsMiddleware) // AI forgets this constantly Blunder 3: CORS applied after routes javascript// Wrong — routes process before CORS headers are set app.use('/api/v1', routes) app.use(cors(options)) // too late, requests already processed

// Correct — CORS must be first app.use(cors(options)) app.options('*', cors(options)) app.use('/api/v1', routes) Blunder 4: Hardcoded origins in production javascript// Wrong — localhost in production CORS means your API is inaccessible from real domains origin: ['http://localhost:3000'] // this is your dev config accidentally shipped to prod Blunder 5: Wrong origin for cookies javascript// Wrong — subdomain doesn't inherit parent domain's cookies // If cookies are set on api.writingplanner.com but origin is writingplanner.com, cookies might not send // Configure carefully: the origin must match EXACTLY where the frontend runs origin: 'https://writingplanner.com' // fine if frontend is at this exact domain // but NOT 'https://app.writingplanner.com' if that's where the frontend actually is

Debugging CORS Errors When you see a CORS error in the browser console, follow this checklist: Step 1: Read the exact error message Access to fetch at 'https://api.yourapp.com' from origin 'https://yourapp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present → Backend is not returning CORS headers at all. Check that app.use(cors(options)) is before routes and that OPTIONS handler exists. The value of 'Access-Control-Allow-Origin' header in the response must not be the wildcard '' when the request's credentials mode is 'include' → You have origin: '' but credentials: true. Change * to your specific frontend URL. Response to preflight request doesn't pass access control check: It does not have HTTP ok status → Your server is returning non-200 for OPTIONS requests. Add app.options('*', corsMiddleware). Step 2: Check with curl bash# Simulate a preflight request curl -X OPTIONS https://api.yourapp.com/projects
-H "Origin: https://yourapp.com"
-H "Access-Control-Request-Method: POST"
-H "Access-Control-Request-Headers: Content-Type"
-v 2>&1 | grep -i "access-control"

Should see in response:

Access-Control-Allow-Origin: https://yourapp.com

Access-Control-Allow-Credentials: true

Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS

If those headers aren't in the response, CORS is misconfigured on the backend.

The Complete Setup for Typical Indie App javascript// config/cors.js — copy this, adjust your domains const cors = require('cors')

const corsOptions = { origin: function(origin, callback) { if (!origin) return callback(null, true) // allow Postman/curl

const allowed = (process.env.ALLOWED_ORIGINS || 'http://localhost:3000,http://localhost:5173')
  .split(',')
  .map(o => o.trim())

if (allowed.includes(origin)) {
  return callback(null, true)
}

console.warn(`CORS blocked: ${origin}`)
callback(new Error(`CORS policy does not allow origin: ${origin}`))

}, credentials: true, methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'], allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'], exposedHeaders: ['X-Total-Count'], // headers frontend is allowed to read maxAge: 86400 }

module.exports = cors(corsOptions)

// app.js const corsMiddleware = require('./config/cors')

app.use(corsMiddleware) app.options('*', corsMiddleware) // handle preflight // ... rest of app bash# .env.example ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

production .env (or platform env var)

ALLOWED_ORIGINS=https://yourapp.com,https://www.yourapp.com

Starter Prompt for Cursor (CORS) Paste before any backend setup work: CORS configuration requirements:

• Never use origin: '*' — always specify exact allowed origins
• Load allowed origins from ALLOWED_ORIGINS environment variable (comma-separated list)
• Set credentials: true since we use httpOnly cookies for auth
• Handle OPTIONS preflight with app.options('*', corsMiddleware) before all routes
• Apply CORS middleware as the FIRST middleware in app.js, before routes
• Allowed methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
• Allowed headers: Content-Type, Authorization
• Set maxAge: 86400 to cache preflight for 24 hours
• Log blocked origins as warnings for debugging
• Local development: allow localhost:3000 and localhost:5173 by default