expressjs / expressjs/cors

Docs should better explain what this package actually does

Open
#384 3 comments 3 reactions 1 assignee Claimed by @jonchurch View on GitHub
docs
Dominant language
JavaScript
Stars
6.2k
Forks
512
PR merge metrics
No merged PRs in 30d

Description

Cutting this issue to track some docs changes I have queued up, and am open to feedback.

CORS is confusing, infamously so. And we will sometimes get users who are confused about what it is and how it works.

I don't really want the README to try and teach folks everything about CORS, but I do want to try and help people out by improving the documentation to hopefully catch some of the repeat issues we see.

So below is a summary of what I've seen across various issues historically here, and some simple suggestions for improving the readme.

## Problem

Users regularly open issues demonstrating misunderstandings about what this package does:

- #365 - User thought `origin: 'http://example.com'` would block other origins server-side
- #109 - "Why run request handlers successfully if the request fails CORS?"
- #296 - User wanted to prevent "malicious requests from Postman"
- #27 - "GET request is returning 200 even when origin not allowed"
- #8 - "Should CORS deny access from curl requests?"

The common thread: **users think CORS is server-side access control**.

The documentation doesn't clearly state what the library actually does, and uses ambiguous language:

- "Enable CORS" / "allow origins" suggests blocking
- "reflect" is jargon that doesn't explain actual header behavior
- No mention that browsers enforce CORS, not servers

## Proposed Improvements

- [x] Add a clear callout explaining that CORS is browser enforced, not server-enforced
- https://github.com/expressjs/cors/pull/385
- [x] Add a "Common Misconceptions" section addressing the patterns seen in issues, that way we have something to link people to within the repo.
- https://github.com/expressjs/cors/pull/385
- [ ] Replace ambiguous language with explicit descriptions of what headers get set
- https://github.com/expressjs/cors/pull/387
- [x] Add comments to code examples showing the actual response headers
- https://github.com/expressjs/cors/pull/386

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.