Docs should better explain what this package actually does
- 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
Assessment
This issue has not been assessed yet.