How to fix those confusing CORS errors when calling your Express API
Tags: express, node, cors
Published: 2020-10-20 10:33:16

---
title: How to fix those confusing CORS errors when calling your Express API
published: true
date: 2020-10-20 10:23:11 UTC
tags: Express,Node,cors
canonical_url: https://simonplend.com/how-to-fix-those-confusing-cors-errors-when-calling-your-express-api/
---

You’ve created an API with Express and you’re busy adding some JavaScript to your front end which will make requests to it. Everything is going great until you load up the front end in your browser and you see a weird error like this in the console:

> `Access to fetch at 'https://your-api.com/user/1234' from origin 'https://your-website.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.`

Perhaps you’ve then tried setting the request’s mode to `no-cors` as the error message suggests, but the request to the API _still_ doesn’t work. Even after a bunch of Googling, it’s hard to wrap your head around why this is happening or how to get around it.

The good news is that there’s a library for Express which you can use to help fix these CORS errors, but before we look at fixing them, what do they actually mean? In order to understand these errors, let’s take a look at _what_ CORS is.

## What is CORS and why is it ruining your day?

CORS stands for Cross-Origin Resource Sharing (CORS) and it’s something which is supported by all modern browsers. It’s a bit of a mouthful, so we’re going to break it down first, and then we can learn about what it _actually_ does.

### What is a "resource"?

A resource is the content which is available at a specific URL e.g. an HTML web page, an image, or a JSON API response. It’s effectively the "stuff" which makes up the world wide web.

### What is an "origin"?

The origin for a resource is the protocol + domain + port e.g. for the URL `https://your-api.com:8080/user/1234` the origin is `https://your-api.com:8080`. If the URL doesn’t contain a port, then the origin will just be the protocol + domain.

### What does Cross-Origin Resource Sharing _actually_ do?

Cross-Origin Resource Sharing is the way in which a web browser ensures that the front end JavaScript of a website (origin A) can only access resources from another origin (origin B) if that origin _explicitly_ allows it to. If it does allow it, then the resource is shared – you guessed it – cross-origin! Phew, we got there in the end.

CORS can help prevent malicious websites from accessing and using data from places that they shouldn’t be. When you see those annoying CORS errors in your browser, it’s actually your web browser doing its best to protect you from what it has identified as a potentially malicious request.

### How does CORS work?

The way in which a web browser figures out whether a resource is allowed to be shared cross-origin is by setting an `Origin` header on requests made by front end JavaScript. The browser then checks for CORS headers set on the resource response. The headers it will check for on the response depend on the type of request which the browser has made, but the response must at least have the `Access-Control-Allow-Origin` header set to an allowed value for the web browser to make the response available to the front end JavaScript which requested it.

### An example CORS request

An example of a cross-origin request would be a `GET` request made with [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) from the front end JavaScript on your web page – which is hosted on one domain (origin A) – to an API endpoint which you host on a different domain (origin B).

The request made by the browser from the JavaScript on your web page at `https://your-website.com/user-profile` would contain this information:

```
> GET /user/1234 HTTP/1.1
> Host: your-api.com
> Origin: https://your-website.com
```

The `Origin` request header is automatically set by the web browser – for security reasons you are not able to set its value when you make the request with `fetch`.

In order for the example CORS request above to work correctly, the response from your API would need to look like this:

```
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: https://your-website.com
< Vary: Origin
< Content-Type: application/json; charset=utf-8
< 

{"name":"Existing Person"}
```

Notice how the value of the `Access-Control-Allow-Origin` response header matches the value of the `Origin` response: `https://your-website.com`. The web browser will see this CORS response header and determine that it has permission to share the response content with the front end JavaScript on your web page.

Now we have a better idea of what CORS is and what it does, it's time to set some CORS headers and fix the errors you're getting on your web page.

## How to set CORS headers and get rid of those annoying errors

As you saw in the example above, it's important for the web browser to send the `Origin` header in the request that it makes to your API, but it's your API which needs to send the all important `Access-Control-*` headers in the response. These CORS headers are what will tell the web browser whether or not it is allowed to make the response from your API available to your front end JavaScript.

The library you're going to use to help fix the CORS errors you've been battling is the [cors middleware package](https://github.com/expressjs/cors). Head to the directory containing your Express application in your terminal, and let's get it installed:

```bash
npm install cors
```

> _Note: In this blog post I'm linking to the `cors` package on GitHub instead of npm as at the time of writing the documentation for this package is out-of-date on on npm._

Once it's installed, you need to require it in your application (directly after you require `express` is fine):

```javascript
const cors = require("cors");
```

If you call the `cors` middleware in your Express application without passing any configuration options, by default it will add the CORS response header `Access-Control-Allow-Origin: *` to your API's responses. This means that _any_ origin - i.e. a web page on any domain - can make requests to your API. Unless you're building an API for the general public to use, this is not the behaviour you want, so let's jump right in to configuring the `cors` middleware so that only _your_ website can make CORS requests to your API:

```javascript
/**
 * These options will be used to configure the cors middleware to add
 * these headers to the response:
 * 
 * Access-Control-Allow-Origin: https://your-website.com
 * Vary: Origin
 */
const corsOptions = {
	origin: "https://your-website.com"
};

/**
 * This configures all of the following routes to use the cors middleware
 * with the options defined above.
 */
app.use(cors(corsOptions));

app.get("/user/:id", (request, response) => {
	response.json({ name: "Existing Person" });
});

app.get("/country/:id", (request, response) => {
	response.json({ name: "Oceania" });
});

app.get("/address/:id", (request, response) => {
	response.json({ street: "Gresham Lane", city: "Lakeville" });
});
```

Typically you'll want to enable CORS for all of the routes in your Express application as in the example above, but if you only want to enable CORS for specific routes you can configure the cors middleware like this:

```javascript
/**
 * These options will be used to configure the cors middleware to add
 * these headers to the response:
 * 
 * Access-Control-Allow-Origin: https://your-website.com
 * Vary: Origin
 */
const corsOptions = {
	origin: "https://your-website.com"
};

// This route is using the cors middleware with the options defined above.
app.get("/user/:id", cors(corsOptions), (request, response) => {
	response.json({ name: "Existing Person" });
});

// This route is using the cors middleware with the options defined above.
app.get("/country/:id", cors(corsOptions), (request, response) => {
	response.json({ name: "Oceania" });
});

/**
 * We never want this API route to be requested from a browser,
 * so we don't configure the route to use the cors middleware.
 */
app.get("/address/:id", (request, response) => {
	response.json({ street: "Gresham Lane", city: "Lakeville" });
});
```

## Enabling "complex" CORS requests

The examples above configure CORS for simple GET requests. For many other types of CORS requests, a CORS "preflight" request will be made by web browsers before the actual CORS request. This preflght request uses the `OPTIONS` HTTP method and it helps the browser determine whether it will be allowed to make the CORS request.

The `cors` middleware provides instructions for [Enabling CORS Pre-Flight](https://github.com/expressjs/cors#enabling-cors-pre-flight), and allows you to [configure the headers](https://github.com/expressjs/cors#configuration-options) that you want to send in the response to a preflight request.

## Fear CORS no more

Hopefully this article has helped you understand what CORS is all about, but there will always be times where it's difficult to figure out how you need to configure things for a CORS request to work. Here are some things that have helped me out along the way:

- [Will it CORS?](https://httptoolkit.tech/will-it-cors/) - This _fantastic_ tool will ask you about what you want to do, and then tell you the exact CORS response headers that you need to send for the CORS request to work correctly.
- [CORS HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#CORS) - A handy reference which lists all of the CORS headers which you can use.
- [Simple requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests) and [Preflighted requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Preflighted_requests) - The CORS documentation on the Mozilla Developer Network has great explanations of the different types of CORS requests.
- [Path of an XMLHttpRequest(XHR) through CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing#/media/File:Flowchart_showing_Simple_and_Preflight_XHR.svg) - This flowchart on Wikipedia is a helpful visual tool for understanding when a CORS request is considered "complex".
- [Fetch standard: HTTP extensions](https://fetch.spec.whatwg.org/#http-extensions) - This documentation covers the nitty gritty details of how CORS is implemented in the browser Fetch API.

Happy cross-origin resource sharing!