What Are the Cache Performance Features of UNPKG?
UNPKG is a global content delivery network (CDN) for files published to npm, and its cache performance comes from two layers working together: immutable versioned URLs that browsers and edge nodes can cache for a long time, and a global edge network that serves repeated requests from a location near the user. The practical result is that a request for a pinned version like unpkg.com/[email protected]/umd/react.production.min.js can be served from cache instead of hitting npm's registry, while a request for a moving target like unpkg.com/react@latest/... is harder to cache because the underlying file can change.
Why Versioned URLs Cache Well
The URL structure unpkg.com/:package@:version/:file is the key mechanism. When you pin an exact version, the content behind that URL never changes — the same version of a package on npm is immutable. That makes the URL safe to cache aggressively at every layer: the browser, intermediate proxies, and UNPKG's own edge nodes.
By contrast:
unpkg.com/[email protected]/dist/preact.min.js— exact version, stable content, cache-friendly.unpkg.com/preact@latest/dist/preact.min.js— resolves to whatever the latest tag points to today, so the content can change when a new version is published.unpkg.com/react@^18/umd/react.production.min.js— a semver range, which can also resolve to a different file over time.
If you don't specify a version at all, UNPKG uses the latest tag by default, so unpkg.com/preact/dist/preact.min.js behaves like the latest case.
Practical takeaway: pin exact versions in production so you get the strongest caching and predictable content. Use latest or ranges only when you deliberately want to track new releases.
The Global Edge Network
UNPKG describes itself as a "fast, global" CDN, which means requests are handled by edge nodes distributed geographically rather than a single origin server. For a user in one region requesting a popular package, the file is likely already cached at a nearby edge node from previous traffic, so the response avoids a round trip to the registry.
This matters most for:
- Popular packages (React, Vue, Preact, Three.js) that see heavy traffic and stay warm in edge caches.
- Repeated requests across many users, where the first request populates the cache and later ones are served quickly.
Less popular or newly published packages may not be cached at every edge node yet, so the first request in a region can be slower than subsequent ones.
Cache Behavior You Should Plan Around
| URL pattern | Content stability | Caching outlook |
|---|---|---|
[email protected]/file.js |
Immutable | Best — safe to cache long-term |
pkg@latest/file.js |
Changes on new publish | Weaker — may be revalidated |
pkg@^1/file.js |
Changes within range | Weaker — may be revalidated |
pkg/file.js (no version) |
Follows latest |
Weaker — same as latest |
A few practical implications:
- Pin versions for production assets. This is the single biggest lever for cache performance and reproducibility.
- Expect first-request latency for cold packages. A package with little traffic may not be cached near your users yet.
- Don't rely on UNPKG for private or frequently changing content. It serves public npm packages, and moving targets undercut caching.
What UNPKG Does Not Change
UNPKG's caching is about delivery speed, not about bypassing npm. The files it serves are the published package contents on npm, so anything you'd change by republishing a version isn't something UNPKG's cache can fix — and republishing the same version isn't how npm versioning works anyway. If you need different content, you publish a new version and update your URL.
For most frontend use cases — loading a library via a <script> tag or an ES module import — pinning an exact version and letting UNPKG's edge network handle distribution gives you the best combination of speed and predictability.