What is cors?
The cors npm package is a middleware for enabling Cross-Origin Resource Sharing (CORS) in web applications using Node.js and Express. It allows you to specify which domains can access resources on your server, which HTTP methods are allowed, and other security-related configurations to prevent or allow cross-site requests.
What are cors's main functionalities?
Basic Usage
This code sample demonstrates the basic usage of the cors package where it enables CORS for all routes and origins by default.
const express = require('express');
const cors = require('cors');
const app = express();
app.use(cors());
app.get('/data', (req, res) => {
res.json({ message: 'This route is CORS-enabled for all origins!' });
});
app.listen(3000, () => {
console.log('Server running on port 3000');
});
Configuring CORS for Specific Origins
This code sample shows how to configure CORS to allow requests from a specific origin, in this case, 'http://example.com'.
const express = require('express');
const cors = require('cors');
const app = express();
const corsOptions = {
origin: 'http://example.com',
optionsSuccessStatus: 200
};
app.use(cors(corsOptions));
app.get('/data', (req, res) => {
res.json({ message: 'This route is CORS-enabled for http://example.com!' });
});
app.listen(3000, () => {
console.log('Server running on port 3000');
});
Enabling CORS for Dynamic Origins
This code sample illustrates how to enable CORS based on a dynamic list of origins. The origins are checked against a whitelist, and CORS is configured accordingly.
const express = require('express');
const cors = require('cors');
const app = express();
const whitelist = ['http://example1.com', 'http://example2.com'];
const corsOptionsDelegate = function (req, callback) {
let corsOptions;
if (whitelist.indexOf(req.header('Origin')) !== -1) {
corsOptions = { origin: true };
} else {
corsOptions = { origin: false };
}
callback(null, corsOptions);
};
app.use(cors(corsOptionsDelegate));
app.get('/data', (req, res) => {
res.json({ message: 'This route has CORS enabled for specific origins!' });
});
app.listen(3000, () => {
console.log('Server running on port 3000');
});
Other packages similar to cors
helmet
Helmet is a middleware for Express applications that sets various HTTP headers to help protect your app from some well-known web vulnerabilities. While it does not provide the same CORS functionality out of the box, it contributes to the overall security of the application, similar to how CORS restricts resource sharing for security purposes.
http-proxy-middleware
This package provides a way to create a proxy middleware for Express applications. It can be used to proxy requests to other servers, effectively bypassing CORS restrictions by making it seem like all requests originate from the same domain. It serves a different purpose but can be used to solve similar cross-origin issues in development environments.
cors
CORS is a node.js package for providing a Connect/Express middleware that can be used to enable CORS with various options.
Follow me (@troygoode) on Twitter!
![NPM](https://nodei.co/npm/cors.png?downloads=true&stars=true)
![build status](https://secure.travis-ci.org/expressjs/cors.svg?branch=master)
Installation (via npm)
$ npm install cors
Usage
Simple Usage (Enable All CORS Requests)
var express = require('express')
, cors = require('cors')
, app = express();
app.use(cors());
app.get('/products/:id', function(req, res, next){
res.json({msg: 'This is CORS-enabled for all origins!'});
});
app.listen(80, function(){
console.log('CORS-enabled web server listening on port 80');
});
Enable CORS for a Single Route
var express = require('express')
, cors = require('cors')
, app = express();
app.get('/products/:id', cors(), function(req, res, next){
res.json({msg: 'This is CORS-enabled for all origins!'});
});
app.listen(80, function(){
console.log('CORS-enabled web server listening on port 80');
});
Configuring CORS
var express = require('express')
, cors = require('cors')
, app = express();
var corsOptions = {
origin: 'http://example.com',
optionsSucccessCode: 200
};
app.get('/products/:id', cors(corsOptions), function(req, res, next){
res.json({msg: 'This is CORS-enabled for only example.com.'});
});
app.listen(80, function(){
console.log('CORS-enabled web server listening on port 80');
});
Configuring CORS w/ Dynamic Origin
var express = require('express')
, cors = require('cors')
, app = express();
var whitelist = ['http://example1.com', 'http://example2.com'];
var corsOptions = {
origin: function(origin, callback){
var originIsWhitelisted = whitelist.indexOf(origin) !== -1;
callback(originIsWhitelisted ? null : 'Bad Request', originIsWhitelisted);
}
};
app.get('/products/:id', cors(corsOptions), function(req, res, next){
res.json({msg: 'This is CORS-enabled for a whitelisted domain.'});
});
app.listen(80, function(){
console.log('CORS-enabled web server listening on port 80');
});
Enabling CORS Pre-Flight
Certain CORS requests are considered 'complex' and require an initial
OPTIONS
request (called the "pre-flight request"). An example of a
'complex' CORS request is one that uses an HTTP verb other than
GET/HEAD/POST (such as DELETE) or that uses custom headers. To enable
pre-flighting, you must add a new OPTIONS handler for the route you want
to support:
var express = require('express')
, cors = require('cors')
, app = express();
app.options('/products/:id', cors());
app.del('/products/:id', cors(), function(req, res, next){
res.json({msg: 'This is CORS-enabled for all origins!'});
});
app.listen(80, function(){
console.log('CORS-enabled web server listening on port 80');
});
You can also enable pre-flight across-the-board like so:
app.options('*', cors()); // include before other routes
Configuring CORS Asynchronously
var express = require('express')
, cors = require('cors')
, app = express();
var whitelist = ['http://example1.com', 'http://example2.com'];
var corsOptionsDelegate = function(req, callback){
var corsOptions;
if(whitelist.indexOf(req.header('Origin')) !== -1){
corsOptions = { origin: true };
}else{
corsOptions = { origin: false };
}
callback(null, corsOptions);
};
app.get('/products/:id', cors(corsOptionsDelegate), function(req, res, next){
res.json({msg: 'This is CORS-enabled for a whitelisted domain.'});
});
app.listen(80, function(){
console.log('CORS-enabled web server listening on port 80');
});
Configuration Options
origin
: Configures the Access-Control-Allow-Origin CORS header. Possible values:
Boolean
- set origin
to true
to reflect the request origin, as defined by req.header('Origin')
, or set it to false
to disable CORS.String
- set origin
to a specific origin. For example if you set it to "http://example.com"
only requests from "http://example.com" will be allowed.RegExp
- set origin
to a regular expression pattern which will be used to test the request origin. If it's a match, the request origin will be reflected. For example the pattern /example\.com$/
will reflect any request that is coming from an origin ending with "example.com".Array
- set origin
to an array of valid origins. Each origin can be a String
or a RegExp
. For example ["http://example1.com", /\.example2\.com$/]
will accept any request from "http://example1.com" or from a subdomain of "example2.com".Function
- set origin
to a function implementing some custom logic. The function takes the request origin as the first parameter and a callback (which expects the signature err [object], allow [bool]
) as the second.
methods
: Configures the Access-Control-Allow-Methods CORS header. Expects a comma-delimited string (ex: 'GET,PUT,POST') or an array (ex: ['GET', 'PUT', 'POST']
).allowedHeaders
: Configures the Access-Control-Allow-Headers CORS header. Expects a comma-delimited string (ex: 'Content-Type,Authorization') or an array (ex: ['Content-Type', 'Authorization']
). If not specified, defaults to reflecting the headers specified in the request's Access-Control-Request-Headers header.exposedHeaders
: Configures the Access-Control-Expose-Headers CORS header. Expects a comma-delimited string (ex: 'Content-Range,X-Content-Range') or an array (ex: ['Content-Range', 'X-Content-Range']
). If not specified, no custom headers are exposed.credentials
: Configures the Access-Control-Allow-Credentials CORS header. Set to true
to pass the header, otherwise it is omitted.maxAge
: Configures the Access-Control-Max-Age CORS header. Set to an integer to pass the header, otherwise it is omitted.preflightContinue
: Pass the CORS preflight response to the next handler.
The default configuration is the equivalent of:
{
"origin": "*",
"methods": "GET,HEAD,PUT,PATCH,POST,DELETE",
"preflightContinue": false
}
For details on the effect of each CORS header, read this article on HTML5 Rocks.
Demo
A demo that illustrates CORS working (and not working) using jQuery is available here: http://node-cors-client.herokuapp.com/
Code for that demo can be found here:
License
MIT License
Author
Troy Goode (troygoode@gmail.com)