How UNPKG serves files
UNPKG is deliberately simple at the edge and careful behind it. Requests are answered by Cloudflare's global network; behind that edge sits a small, verified path back to the npm tarball your file came from.
The path of a request
- Browser cacheExact-version files, up to a year. Shield-pinned responses are never stored here.
- Cloudflare edge cacheThe hot path. Permanent URLs served near the user; hits never reach the origin.
- Worker cache layersFile and listing caches keyed by package@version, and by cache generation after an eviction.
- File originVerified fetches with retries and resume; corrupt entries are evicted and healed.
- npm tarballThe source of truth: byte-for-byte what the maintainer published.
Edge caching meets supply chain security
Exact-version URLs (like /react@18.3.1/umd/react.production.min.js) are immutable in practice, so they are cached at the edge for a year. Range and tag URLs redirect to the exact version first, which keeps the hot path pinned to those long-lived entries. Because cached bytes are digest-verified, a truncated or damaged entry cannot quietly persist: it fails verification, is evicted, and is refetched complete. When a version must be withdrawn, operators can evict that exact package@version from every cache layer without touching any other version.
A year-long cache would be a liability if it kept serving a compromised release, so for domains armed with UNPKG Shield the check runs before any cache lookup: a bad version is rewritten to the last known-good one (or blocked) before a cached copy can be served.
What happens when
| Request | Behavior |
|---|---|
| Exact version + file | Served from the edge under a permanent URL; cached for a year. |
| Range or tag | Redirects to the resolved exact version, which is then cached as above. |
| Shield-pinned version | Rewritten to the known-good version before any cache lookup; the browser never stores the substitute. |
| Withdrawn version | Its cache generation is evicted in every layer; the next request refetches (or 404s if npm removed it). |
A multi-region origin
Our file origin runs in 11 regions, so a cold fetch stays on the same side of the planet as the edge location asking for it. Origin fetches retry automatically, and large files stream with resume instead of starting over.
Americas
- Dallas
- Secaucus
- Los Angeles
- San Jose
- São Paulo
Europe
- Amsterdam
- Paris
- London
Asia-Pacific
- Singapore
- Tokyo
- Sydney
Supply-chain defense at the same edge
UNPKG Shield is an optional layer on top of UNPKG, not part of the base service: files are served exactly the same whether or not a domain uses it. For domains that have armed it, the check runs in the Worker on the request path above, before any cache is consulted; a matched version is rewritten to a known-good one (or blocked) and then cached under the clean version's key. Domains that register start in monitoring; enforcement is a deliberate opt-in. How Shield classifies releases and how to join are covered at shield.unpkg.com.
The trade we chose, stated plainly
UNPKG runs on one edge provider, Cloudflare, instead of spreading traffic across several CDNs. That is a real trade: we give up multi-provider failover. In return, the edge, the cache layers, Shield enforcement, and our testing infrastructure all behave as one system, which is what makes the verified-caching and hot-swap behavior above possible.
Getting the fastest response
Pin the full version and file path in production URLs. Exact-version requests hit the long-lived edge cache; unpinned requests pay a redirect first. The guides cover the URL patterns in detail.