Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 39 ยท Streaming and Performance

HTTP Caching and Headers

Speed up Remix and React Router apps with HTTP caching: export headers, set Cache-Control and stale-while-revalidate, use ETag and 304 responses, and avoid caching private pages.

The fastest request is the one that never reaches your server. Because Remix and React Router framework mode are built on the platform, they use ordinary HTTP caching: you tell browsers and CDNs how long a response stays fresh with headers such as Cache-Control, and they obey. No special cache API is needed. This lesson shows how to set headers from route modules and how to choose the right policy for each kind of response.

Setting headers on a route

A route module may export headers. It runs on the server and returns the headers for the HTML document response:

TSX
// app/routes/articles.$slug.tsx (React Router framework mode, read-only)
import type { Route } from "./+types/articles.$slug";

export function headers(_: Route.HeadersArgs) {
  return {
    "Cache-Control": "public, max-age=60, s-maxage=3600, stale-while-revalidate=86400",
  };
}

You can also set headers from a loader by returning data(value, { headers }). When several routes in a hierarchy contribute headers, the framework gives you the headers of the loader and the parent so you can merge them; a common rule is to use the shortest cache lifetime among the matched routes, since the document contains all their data.

The vocabulary of Cache-Control

Directive Meaning
public any cache (browser, CDN) may store it
private only the visitor's own browser may store it
max-age=N fresh for N seconds in the browser
s-maxage=N fresh for N seconds in shared caches such as a CDN (overrides max-age there)
stale-while-revalidate=N after expiry, serve the stale copy for up to N more seconds while fetching a fresh one in the background
no-cache may store, but must check with the server before each use
no-store do not store at all
immutable will never change; do not even revalidate

A good default for a public article: public, max-age=60, s-maxage=3600, stale-while-revalidate=86400. Visitors may reuse the page for a minute, the CDN holds it an hour, and when it expires the next visitor still gets an instant (slightly old) response while a refresh happens behind the scenes.

Node.js Stand-in: a tiny cache that obeys max-age and stale-while-revalidate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Validation: ETag and 304

When a cached copy expires, the browser can ask "has this changed?" instead of downloading everything. The server sends an ETag (a fingerprint of the content). The browser repeats it in If-None-Match; if the content is unchanged the server replies 304 Not Modified with no body, saving bandwidth. A route that serves an API-like response can compute the ETag from the content.

Node.js Stand-in: ETag and 304

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

What never to cache publicly

Anything that depends on the signed-in user must not be stored by a shared cache, or one visitor could be served another visitor's page. Send Cache-Control: private, no-store on pages that include account data, and never cache responses that set cookies (Set-Cookie) on a CDN. Many CDNs refuse to cache such responses by default, but do not rely on that. A pattern that keeps the best of both: serve a cacheable public shell and fetch the per-user bits from a separate uncached route after load.

Static assets: fingerprinted and immutable

The build emits JavaScript and CSS with a content hash in the file name (/assets/entry.client-Bq3k.js). A new build means a new URL, so these files can be cached for a year:

Text
Cache-Control: public, max-age=31536000, immutable

Frameworks normally set this for the /assets folder. Keep unhashed files, such as favicon.ico, on a short lifetime.

Cache by route type

Response Suggested policy
Marketing page, article public, max-age=60, s-maxage=3600, stale-while-revalidate=86400
Product listing public, max-age=0, s-maxage=60, stale-while-revalidate=600
Dashboard, account private, no-store
Fingerprinted assets public, max-age=31536000, immutable
Search results public, max-age=0, s-maxage=30 (consider carefully)

Purging

When you publish an edit, shared caches keep the old page until it expires. Use your CDN's purge-by-URL or purge-by-tag API in the code that publishes content, and keep s-maxage modest unless you can purge.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does s-maxage control?

    s-maxage applies to shared caches and overrides max-age there.
  2. 2. What does stale-while-revalidate allow?

    Visitors get an instant response, and the next visitor receives the refreshed copy.
  3. 3. A server answers an If-None-Match request with 304. What does the body contain?

    304 means unchanged, so no body is sent.
  4. 4. Which policy suits an account page showing personal data?

    Personal pages must never be stored by shared caches.

Summary

  • Export headers from a route (or return headers from a loader) to control document caching.
  • Combine max-age, s-maxage and stale-while-revalidate; validate with ETag and 304.
  • Fingerprinted assets are immutable for a year; personal pages are private, no-store.
  • Purge shared caches when content changes.

Next: Prefetching and Pending UI