cors

cors is a lightweight Node.js middleware for Express and Connect applications that adds Cross-Origin Resource Sharing (CORS) response headers to HTTP requests. Rather than blocking anything itself, it configures the Access-Control-* headers browsers use to decide whether client-side JavaScript from another origin may read a response, letting you enable open access, lock requests to specific origins, or compute permissions dynamically per request.

With tens of millions of weekly downloads, it has become the de facto standard for handling CORS in the Express ecosystem, valued for its tiny single-file implementation, sane defaults, and flexible configuration options covering static origins, regular expressions, arrays, and asynchronous origin callbacks.

What You Get

• A single cors() Express/Connect middleware function you can mount globally or per-route
• Support for static origins, regex patterns, arrays of origins, and async origin-validation callbacks
• Built-in handling of CORS preflight (OPTIONS) requests, including a configurable success status code for legacy browsers
• Fine-grained control over allowed/exposed headers, credentials, and max-age caching of preflight results

Common Use Cases

• Enabling a public REST API to be called from browser JavaScript hosted on a different domain
• Restricting cross-origin access to a fixed whitelist of trusted frontend origins
• Dynamically validating request origins against a database-backed allowlist per request
• Supporting credentialed (cookie-based) cross-origin requests between a SPA and its API server

Under The Hood

Architecture: cors ships as a single-file library (lib/index.js, ~230 lines) wrapped in an IIFE and exposed via module.exports. The public export, middlewareWrapper, normalizes whatever was passed in—a static options object or a (req, cb) delegate function—into a uniform async callback shape, then returns the actual corsMiddleware(req, res, next) Express handler. On each request, that handler resolves the effective options, resolves the effective origin (which may itself be computed asynchronously via a user-supplied function), and calls an internal cors() function that branches on whether the request is a CORS preflight (OPTIONS) or an actual request. Each branch assembles a nested array of header descriptor objects from small single-purpose configureOrigin/configureMethods/configureCredentials/configureAllowedHeaders/configureExposedHeaders/configureMaxAge functions, which applyHeaders then flattens recursively and writes onto the response (routing Vary headers through the separate vary package to merge correctly with any headers already present).

Tech Stack: The library targets plain Node.js with no build step and deliberately old-school ES5 syntax (var, IIFE, no arrow functions or classes) to keep compatibility back to engines.node >= 0.10. It has exactly two runtime dependencies: object-assign (an Object.assign polyfill, mirroring Express’s own low-dependency philosophy) and vary (for correctly appending to the Vary header). Development tooling is equally minimal: eslint for linting, mocha + supertest for running assertions against real Express apps, and nyc for coverage reporting.

Code Quality: Test coverage is substantial relative to the implementation size—test/test.js alone runs to 731 lines, supplemented by test/example-app.js, test/error-response.js, and a regression test for a specific historical GitHub issue (test/issue-2.js), all exercised against live supertest-driven Express servers rather than mocked requests. Function names (configureOrigin, isOriginAllowed, applyHeaders) are consistently descriptive, and the callback-first error propagation follows standard Node.js conventions throughout. The codebase carries no TypeScript and no bundled type declarations (types are maintained separately via @types/cors on DefinitelyTyped), and there is no JSDoc on internal functions, which is the main gap for a library of its ubiquity.

API Design: The module exports a single default function that can be called with no arguments for permissive defaults, a static options object, or an async options/origin delegate for advanced per-request logic—covering the simple case and the complex case with one consistent call shape. Option names (origin, methods, allowedHeaders, credentials, maxAge) map directly onto the CORS specification’s own vocabulary, so developers already familiar with the browser CORS model incur almost no additional learning overhead, and the middleware can be mounted globally or scoped to a single route without any API changes.