Neoclassical Philosophic Musings

    cors
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/cors package

    2.1.0 • Public • Published

    cors

    CORS is a node.js package for providing a connect/express middleware that can be used to enable CORS with various options.

    NPM

    build status

    Installation (via npm)

    $ npm install cors

    Usage

    Simple Usage (Enable All CORS Requests)

    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'
    };
     
    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 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 }; // reflect (enable) the requested origin in the CORS response
      }else{
        corsOptions = { origin: false }; // disable CORS for this request
      }
      callback(null, corsOptions); // callback expects two parameters: error and options
    };
     
    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');
    });

    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 preflighting, 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()); // enable preflight request for DELETE request
    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');
    });

    Enabling CORS Application-wide

    Rather than turning-on/configuring CORS on a per-resource/route basis, you can do so across your entire application if desired:

    var express = require('express')
      , cors = require('cors')
      , app = express();
     
    app.use(cors()); // automatically supports pre-flighting
    app.use(app.router);
     
    app.get('/products/:id', function(req, res, next){ // didn't have to specify the cors() middleware here this time
      res.json({msg: 'This is CORS-enabled for all origins!'});
    });
     
    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. Expects a string (ex: "http://example.com"). Set to true to reflect the request origin, as defined by req.header('Origin'). Set to false to disable CORS.
    • 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']).
    • headers: 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.
    • 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-Allow-Max-Age CORS header. Set to an integer to pass the header, otherwise it is omitted.

    For details on the effect of each CORS header, read this article on HTML5 Rocks.

    License

    MIT License

    Author

    Troy Goode (troygoode@gmail.com)

    Install

    npm i cors@2.1.0

    Version

    2.1.0

    License

    MIT

    Last publish

    Collaborators

    • dougwilson
    • troygoode