Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 39 ยท Loaders and Data Loading

Client Loaders and Hydration

Learn when to use clientLoader in React Router v7 framework mode, how HydrateFallback works, how to cache data in the browser, and how SPA mode changes loading.

A server loader runs on the server. React Router also lets a route export clientLoader, which runs only in the browser. It is useful when data lives in the browser (IndexedDB, in-memory caches), when you want to call an API directly from the client, or when you build a static single-page app with no server rendering at all.

The framework cannot run on this site, so the TypeScript here is read-only; the stand-ins model the caching and ordering logic in plain JavaScript.

The basic shape

TSX
import type { Route } from "./+types/product";

export async function clientLoader({ params }: Route.ClientLoaderArgs) {
  const res = await fetch(`/api/products/${params.id}`);
  if (!res.ok) throw new Response("Not found", { status: 404 });
  return res.json();
}

export default function Product({ loaderData }: Route.ComponentProps) {
  return <h1>{loaderData.name}</h1>;
}

If a route has only clientLoader, the server cannot render the page's data. On the very first load the server renders nothing for that route, hydrates, then runs the client loader. To avoid a blank screen, export a HydrateFallback component: it is rendered on the server and during hydration while client loaders run.

TSX
export function HydrateFallback() {
  return <p>Loading product...</p>;
}

Both loaders together

A route can export both. The server loader runs on the initial document request. After that, every client navigation to the route calls clientLoader, and you decide whether to call the server loader by calling serverLoader() inside it.

TSX
let cache: Map<string, unknown> | undefined;

export async function clientLoader({ params, serverLoader }: Route.ClientLoaderArgs) {
  cache ??= new Map();
  if (cache.has(params.id)) return cache.get(params.id);
  const data = await serverLoader();      // network round trip
  cache.set(params.id, data);
  return data;
}

This pattern gives you a browser cache in front of a server loader. If you also want the first page load to run the client loader (for example to populate the cache), set clientLoader.hydrate = true and provide a HydrateFallback.

JS Stand-in: a client cache in front of a slow server loader

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

No output.

The danger of any cache is staleness. The next lesson on actions explains revalidation, and you can also clear the cache from clientAction after a mutation.

Skipping revalidation

After actions, React Router reruns the active loaders so the page shows fresh data. With client loaders you can control this with shouldRevalidate:

TSX
export function shouldRevalidate({ formAction, defaultShouldRevalidate }: Route.ShouldRevalidateFunctionArgs) {
  if (formAction === "/preferences") return false;   // that action cannot change this data
  return defaultShouldRevalidate;
}

Use it sparingly: a wrong false shows stale data.

SPA mode

If you set ssr: false in react-router.config.ts, the build produces a static index.html with no server rendering at runtime. Then only client loaders and client actions exist; server loader functions are not allowed. The root route's HydrateFallback becomes the shell shown while the first client loader runs. SPA mode is a good fit for apps behind a login that do not need SEO, deployed to any static host.

TypeScript
// react-router.config.ts
import type { Config } from "@react-router/dev/config";
export default { ssr: false } satisfies Config;

You can also pre-render chosen URLs at build time (prerender: ["/", "/about"]) while the rest renders on the server or as an SPA.

JS Stand-in: HydrateFallback then data

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

No output.

When to choose which

flowchart TD
  A["Where does the data live?"] -->|"database or secret API key"| B["loader (server)"]
  A -->|"browser storage or a public API"| C["clientLoader"]
  A -->|"server data, but cache it in the browser"| D["both: clientLoader calls serverLoader()"]
  A -->|"no server at all"| E["ssr: false + clientLoader"]

Server loaders keep secrets safe; client loaders trade that for browser access and caching.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is HydrateFallback for?

    It renders until clientLoader data is ready on the first load.
  2. 2. Inside clientLoader, how do you reach the route's server loader?

    clientLoader receives serverLoader as an argument.
  3. 3. In SPA mode (ssr: false), which loaders may a route have?

    There is no runtime server, so server loaders are not allowed.
  4. 4. Why should API secrets never be used in a clientLoader?

    Everything in client code ships to the browser.

Summary

  • clientLoader runs in the browser; combine it with serverLoader() for client-side caching.
  • Provide HydrateFallback when a route relies on client loaders for the first render.
  • ssr: false makes an SPA where only client loaders exist; prerender produces static pages for chosen URLs.
  • Cache carefully and control revalidation with shouldRevalidate.

Next: Database Access Patterns