Repository files navigation

CORS is a node.js package for providing aConnect/Express middleware that can be used to enableCORS with various options.

Follow me (@troygoode) on Twitter!

• Installation
• Usage
  • Simple Usage
  • Enable CORS for a Single Route
  • Configuring CORS
  • Configuring CORS w/ Dynamic Origin
  • Enabling CORS Pre-Flight
  • Customizing CORS Settings Dynamically per Request
• Configuration Options
• License
• Author

This is aNode.js module available through thenpm registry. Installation is done using thenpm install command:

$ npm install cors

varexpress=require('express')varcors=require('cors')varapp=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')})

varexpress=require('express')varcors=require('cors')varapp=express()app.get('/products/:id',cors(),function(req,res,next){res.json({msg:'This is CORS-enabled for a Single Route'})})app.listen(80,function(){console.log('CORS-enabled web server listening on port 80')})

See theconfiguration options for details.

varexpress=require('express')varcors=require('cors')varapp=express()varcorsOptions={origin:'http://example.com',optionsSuccessStatus:200// some legacy browsers (IE11, various SmartTVs) choke on 204}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')})

This module supports validating the origin dynamically using a function providedto theorigin option. This function will be passed a string that is the origin(orundefined if the request has no origin), and acallback with the signaturecallback(error, origin).

Theorigin argument to the callback can be any value allowed for theoriginoption of the middleware, except a function. See theconfiguration options section for more information on allthe possible value types.

This function is designed to allow the dynamic loading of allowed origin(s) froma backing datasource, like a database.

varexpress=require('express')varcors=require('cors')varapp=express()varcorsOptions={origin:function(origin,callback){// db.loadOrigins is an example call to load// a list of origins from a backing databasedb.loadOrigins(function(error,origins){callback(error,origins)})}}app.get('/products/:id',cors(corsOptions),function(req,res,next){res.json({msg:'This is CORS-enabled for an allowed domain.'})})app.listen(80,function(){console.log('CORS-enabled web server listening on port 80')})

Certain CORS requests are considered 'complex' and require an initialOPTIONS request (called the "pre-flight request"). An example of a'complex' CORS request is one that uses an HTTP verb other thanGET/HEAD/POST (such as DELETE) or that uses custom headers. To enablepre-flighting, you must add a new OPTIONS handler for the route you wantto support:

varexpress=require('express')varcors=require('cors')varapp=express()app.options('/products/:id',cors())// enable pre-flight request for DELETE requestapp.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

NOTE: When using this middleware as an application level middleware (forexample,app.use(cors())), pre-flight requests are already handled for allroutes.

For APIs that require different CORS configurations for specific routes or requests, you can dynamically generate CORS options based on the incoming request. Thecors middleware allows you to achieve this by passing a function instead of static options. This function is called for each incoming request and must use the callback pattern to return the appropriate CORS options.

The function accepts:

1. req:

   • The incoming request object.

2. callback(error, corsOptions):

   • A function used to return the computed CORS options.
   • Arguments:
     • error: Passnull if there’s no error, or an error object to indicate a failure.
     • corsOptions: An object specifying the CORS policy for the current request.

Here’s an example that handles both public routes and restricted, credential-sensitive routes:

vardynamicCorsOptions=function(req,callback){varcorsOptions;if(req.path.startsWith('/auth/connect/')){corsOptions={origin:'http://mydomain.com',// Allow only a specific origincredentials:true,// Enable cookies and credentials};}else{corsOptions={origin:'*'};// Allow all origins for other routes}callback(null,corsOptions);};app.use(cors(dynamicCorsOptions));app.get('/auth/connect/twitter',function(req,res){res.send('CORS dynamically applied for Twitter authentication.');});app.get('/public',function(req,res){res.send('Public data with open CORS.');});app.listen(80,function(){console.log('CORS-enabled web server listening on port 80')})

• origin: Configures theAccess-Control-Allow-Origin CORS header. Possible values:
  • Boolean - setorigin totrue to reflect therequest origin, as defined byreq.header('Origin'), or set it tofalse to disable CORS.
  • String - setorigin to a specific origin. For example, if you set it to
    • "http://example.com" only requests from "http://example.com" will be allowed.
    • "*" for all domains to be allowed.
  • RegExp - setorigin 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 - setorigin to an array of valid origins. Each origin can be aString or aRegExp. For example["http://example1.com", /\.example2\.com$/] will accept any request from "http://example1.com" or from a subdomain of "example2.com".
  • Function - setorigin to a function implementing some custom logic. The function takes the request origin as the first parameter and a callback (called ascallback(err, origin), whereorigin is a non-function value of theorigin option) as the second.
• methods: Configures theAccess-Control-Allow-Methods CORS header. Expects a comma-delimited string (ex: 'GET,PUT,POST') or an array (ex:['GET', 'PUT', 'POST']).
• allowedHeaders: Configures theAccess-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'sAccess-Control-Request-Headers header.
• exposedHeaders: Configures theAccess-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 theAccess-Control-Allow-Credentials CORS header. Set totrue to pass the header, otherwise it is omitted.
• maxAge: Configures theAccess-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.
• optionsSuccessStatus: Provides a status code to use for successfulOPTIONS requests, since some legacy browsers (IE11, various SmartTVs) choke on204.

The default configuration is the equivalent of:

{"origin":"*","methods":"GET,HEAD,PUT,PATCH,POST,DELETE","preflightContinue":false,"optionsSuccessStatus":204}

For details on the effect of each CORS header, readthis article on web.dev.

MIT License

Troy Goode (troygoode@gmail.com)