Understanding CORS (Cross-Origin Resource Sharing) and How to Configure It with Koa

Cross‑Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to tell browsers that a web application running on one origin (domain, protocol, or port) is allowed to access specified resources on a different origin.

The same‑origin policy requires the domain, protocol, and port to be identical; otherwise the browser blocks the request.

Cross‑origin occurs when the browser cannot execute scripts from another site because of this security restriction.

Example: a simple Koa server is created (see the image) and a front‑end page running on port 3000 requests the /api endpoint. Because the ports differ, the browser reports a CORS error indicating the missing “Access‑Control‑Allow‑Origin” header.

By adding the appropriate header on the server (e.g., Access-Control-Allow-Origin: * ), the front‑end can receive the response successfully.

A request that meets all of the following conditions is considered a “simple request”:

Method is GET, HEAD, or POST.

Only allowed header fields are set (Accept, Accept‑Language, Content‑Language, Content‑Type with values application/x‑www‑form‑urlencoded, multipart/form‑data, or text/plain, etc.).

No XMLHttpRequestUpload event listeners are registered.

No ReadableStream is used.

If a request does not satisfy the simple‑request criteria, the browser first sends an OPTIONS preflight request to the server to determine whether the actual request is permitted.

The preflight request includes the headers Access-Control-Request-Method (the method that will be used) and Access-Control-Request-Headers (any custom headers). The server must respond with Access-Control-Allow-Methods and Access-Control-Allow-Headers accordingly.

Koa provides a dedicated CORS middleware that simplifies this configuration.

For cross‑origin requests that need to send cookies, the client must set credentials: "include" (fetch) or withCredentials: "include" (XMLHttpRequest), and the server must set Access-Control-Allow-Credentials: true and specify a concrete origin instead of "*" in Access-Control-Allow-Origin .

Because a preflight adds an extra OPTIONS request, it can impact performance. To mitigate this, you can convert requests to simple ones when possible and use the Access-Control-Max-Age header to cache the preflight response (e.g., for 10 minutes), reducing the frequency of OPTIONS calls.

Images illustrating the server logs, error messages, and request/response flows are included throughout the article.