Understanding CORS and How to Handle It

Your React app on localhost:5173 calls the API on localhost:8000. The same request works in Postman and with cURL, the server logs show a 200, and yet the browser console shows a red CORS error and your fetch rejects with a vague TypeError: Failed to fetch. Most people's first move is to paste Access-Control-Allow-Origin: * somewhere and hope.

This post explains what's actually going on: why the browser blocks the response, how simple and preflight requests differ, which headers matter, and how to configure CORS properly in Node.js, Express, Laravel and Nginx without opening a hole in your API.

What is CORS?

Browsers start from the Same-Origin Policy (SOP): JavaScript on one origin can't read responses from another origin. Cross-Origin Resource Sharing (CORS) is the way a server says "this other origin is allowed to read my responses." Without it, scripts can send cross-origin requests, but they don't get to see what comes back.

An origin is three things: the protocol (http/https), the domain (example.com) and the port (80, 443, 3000, etc.). Change any one of them and you're cross-origin. That's why localhost:3000 talking to localhost:8000 trips CORS even though it's the same machine.

Why Does CORS Exist?

The restriction protects users, not servers. Your browser holds cookies for every site you're logged into. Without the Same-Origin Policy, any page you open could use them:

• Steal sensitive data: read your webmail, your bank balance, anything behind a login
• Act on your behalf: transfer money, change passwords, post content you never wrote
• Ride your sessions: use your logged-in cookies against any site you're authenticated to

CORS is a controlled hole in that wall. The server lists which origins may read its responses, and the browser enforces that list. Your SPA on app.com gets to talk to api.app.com, and a random site still doesn't.

How CORS Works

On a cross-origin request, the browser adds an Origin header, then looks at the response headers to decide whether your JavaScript gets to see the result. All of the server's policy lives in those headers.

Simple Requests vs. Preflight Requests

There are two kinds of request here. Simple requests go straight to the server. Anything else gets a preflight: the browser first sends an OPTIONS request asking permission, and only sends the real request if the answer is yes.

The CORS Headers You'll Actually Use

There aren't many of them. Most bugs come from one of these being missing or slightly wrong.

Response Headers (Server → Browser)

Request Headers (Browser → Server)

The Classic CORS Error

You've seen this one, probably in Chrome:

It means the response came back without an Access-Control-Allow-Origin header, or with one that didn't match the requesting origin. Your code only sees a generic network error; the detailed reason is only in the console.

Implementing CORS

Pick the layer that owns your responses. If the app framework handles CORS, don't also add headers in Nginx, or you'll end up with duplicates.

const http = require('http');

const server = http.createServer((req, res) => {
  // Set CORS headers
  res.setHeader('Access-Control-Allow-Origin', 'https://myapp.com');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  res.setHeader('Access-Control-Max-Age', '86400');

  // Handle preflight requests
  if (req.method === 'OPTIONS') {
    res.writeHead(204);
    res.end();
    return;
  }

  // Your actual route handling
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ message: 'Hello from API' }));
});

server.listen(3000);

const express = require('express');
const cors = require('cors');
const app = express();

// Simple usage - allow all origins (not for production!)
app.use(cors());

// Production-ready configuration
const corsOptions = {
  origin: ['https://myapp.com', 'https://admin.myapp.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
  credentials: true, // Allow cookies
  maxAge: 86400, // Cache preflight for 24 hours
  exposedHeaders: ['X-Request-Id'] // Headers client can access
};

app.use(cors(corsOptions));

// Dynamic origin based on request
const dynamicCors = cors({
  origin: (origin, callback) => {
    const allowedOrigins = ['https://myapp.com', 'https://staging.myapp.com'];
    
    // Allow requests with no origin (mobile apps, curl)
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  }
});

app.use(dynamicCors);

<?php

return [
    /*
     * Which paths should handle CORS
     */
    'paths' => ['api/*', 'sanctum/csrf-cookie'],

    /*
     * Matches request origins against patterns
     */
    'allowed_origins' => [
        'https://myapp.com',
        'https://admin.myapp.com',
    ],
    
    // Or use patterns
    'allowed_origins_patterns' => [
        'https://*.myapp.com',
    ],

    'allowed_methods' => ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],

    'allowed_headers' => ['Content-Type', 'Authorization', 'X-Requested-With'],

    'exposed_headers' => ['X-Request-Id'],

    'max_age' => 86400,

    'supports_credentials' => true,
];

server {
    listen 443 ssl;
    server_name api.example.com;

    location /api/ {
        # CORS headers
        add_header 'Access-Control-Allow-Origin' 'https://myapp.com' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization' always;
        add_header 'Access-Control-Allow-Credentials' 'true' always;
        add_header 'Access-Control-Max-Age' 86400 always;

        # Handle preflight requests
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin' 'https://myapp.com';
            add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
            add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization';
            add_header 'Access-Control-Max-Age' 86400;
            add_header 'Content-Length' 0;
            add_header 'Content-Type' 'text/plain';
            return 204;
        }

        proxy_pass http://backend;
    }
}

CORS with Credentials

Once cookies or HTTP auth are involved, the rules get stricter. You need all three of these, and missing any one gives you a CORS error.

// Fetch API
fetch('https://api.example.com/user', {
  method: 'GET',
  credentials: 'include', // Include cookies
  headers: {
    'Content-Type': 'application/json',
  }
});

// Axios
axios.get('https://api.example.com/user', {
  withCredentials: true // Include cookies
});

// Axios global config
axios.defaults.withCredentials = true;

Common CORS Errors and Solutions

res.setHeader('Access-Control-Allow-Origin', 'https://your-frontend.com');

// Wrong: port mismatch
'https://localhost:3000' !== 'https://localhost:3001'

// Wrong: trailing slash
'https://app.com/' !== 'https://app.com'

// Wrong: www mismatch  
'https://www.app.com' !== 'https://app.com'

res.setHeader('Access-Control-Allow-Headers', 
  'Content-Type, Authorization, X-Custom-Header');

res.setHeader('Access-Control-Allow-Methods', 
  'GET, POST, PUT, DELETE, PATCH, OPTIONS');

const allowedOrigins = ['https://app.com', 'https://admin.app.com'];
const origin = req.headers.origin;

if (allowedOrigins.includes(origin)) {
  res.setHeader('Access-Control-Allow-Origin', origin);
  res.setHeader('Access-Control-Allow-Credentials', 'true');
}

Security Best Practices

Every line of a CORS config decides who can read your API's responses from a browser. Treat it like any other access rule:

Development Workarounds

Locally you often just want the frontend to talk to the API. These are the options, from best to worst:

export default {
  server: {
    proxy: {
      // Proxy /api requests to backend
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
}

Debugging CORS Issues

Start in the browser's dev tools, then confirm with cURL:

# Check simple request headers
curl -I -H "Origin: https://myapp.com" \
  https://api.example.com/data

# Simulate preflight request
curl -X OPTIONS \
  -H "Origin: https://myapp.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type, Authorization" \
  -I https://api.example.com/data

# Look for these in response:
# Access-Control-Allow-Origin: https://myapp.com
# Access-Control-Allow-Methods: POST, GET, ...
# Access-Control-Allow-Headers: Content-Type, Authorization

What to Check Before Going to Production

And remember what CORS doesn't do. It isn't authentication and it doesn't stop cURL, scripts or other servers from calling your API. It only controls what browsers let other sites read. Your API still needs real auth, and for cookie-based sessions, CSRF protection too.

Mayur Dabhi

Full-stack developer specializing in Laravel, React, and Node.js. Writing about web development, APIs, and best practices.