Fetch API — Understanding Request.cache

#webdev

When a webpage sends a request, it usually uses HTTP Cache. The Request.cache property in the Fetch API lets you tell the browser how it should handle caching for that particular request.

Before diving in, let's quickly clarify two common cache terms you need to know:

Fresh – The cached resource is still valid; the browser can safely use it without checking the server.
Stale – The cache is expired or potentially outdated; the browser might need to revalidate it with the server before using it. These two concepts are the foundation of how HTTP caching decides whether to use or refresh stored data.

Okay, let's break down how each cache mode works.

🔍 The Six Cache Modes

The Fetch API supports six different cache modes you can set:

type RequestCache = "default" | "force-cache" | "no-cache" | "no-store" | "only-if-cached" | "reload";

default
Uses the browser's default cache behavior.

If there's no cached resource, it'll fetch it from the server.
If the cache exists and hasn't expired, it'll use it directly.
If the cache exists but is expired, the browser sends a conditional request to check with the server — if the resource hasn't changed, it reuses the cache; otherwise, it downloads the new resource and updates the cache.

no-store
Always fetches from the server without reading or writing to the cache. Basically, every request is a fresh one.

reload
Doesn't use the cache at all — always fetches from the server, but once it gets the resource, it updates the cache with it.

no-cache
Pretty similar to default, but with one key difference:
Even if a cache exists (whether is fresh or stale), it still sends a request to the server to check if the resource has changed.

If it hasn't, it uses the cached version
If it has, it fetches the new one and stores it in the cache
If there's no cache at all, it just fetches from the server.

force-cache
Always tries to use the cached version first. Only if there's no matching cache entry will it make a network request and then store the new response in the cache.

only-if-cached
Only serves from the cache — no network request at all. If the cache doesn't have the resource, the request fails with HTTP 504 (Gateway timeout).
Note: only-if-cached only works when mode is set to same-origin

🧩 Choosing the Right Cache Mode (Examples)

Imagine you're building a dashboard that shows real-time stock prices. You definitely don't want stale data, so you'd go with:

fetch(url, { cache: 'no-store' })

This ensures every request hits the server and gets the latest prices, no cache involved.

But for something like a user profile photo or a static JSON config, you don't need to fetch it every single time. In that case, using force-cache or even the default mode works better:

fetch(url, { cache: 'force-cache' })

That way, the browser loads it instantly from cache if it's already available, and only fetches again when necessary — faster and more efficient.

🍺 Wrapping Up

Use no-store when you always need the newest data.
Use force-cache or default for static assets or infrequently updated content.
Use no-cache when you want freshness but still leverage conditional requests.
Use reload to refresh your cache with the latest version.
Use only-if-cached only if you want offline-only behavior.