Avoiding request waterfalls

A waterfall is serial latency on data that has no serial dependency. The tell is two awaits back to back where the second argument doesn’t use the first result. Each await parks the function until its promise settles, so the requests run nose-to-tail and the total time is the sum of the round trips instead of the max.

// waterfall: user and posts are independent, but run serially
async function load(userId: string) {
  const user = await fetchUser(userId);    // 300ms
  const posts = await fetchPosts(userId);  // 300ms — starts only after user resolves
  return { user, posts };                  // total ≈ 600ms
}

fetchPosts never reads user. There is no reason for it to wait. The fix is to start both before awaiting either, so the round trips overlap.

Fix independent requests by kicking them off together, then awaiting the group — Promise.all. Start the promises first (don’t await yet), then await them as a set. Now the two round trips overlap and total time collapses from sum to max.

// parallel: both requests are in flight before either is awaited
async function load(userId: string) {
  const userP = fetchUser(userId);    // started, not awaited
  const postsP = fetchPosts(userId);  // started, not awaited
  const [user, posts] = await Promise.all([userP, postsP]); // ≈ 300ms total
  return { user, posts };
}

The structural shift is small but exact: create the promises eagerly, await them late. If one rejects, Promise.all rejects immediately — use Promise.allSettled when a partial result should still render. This is the same move whether you’re in a route loader, a server action, or a plain async function.

In RSC, the waterfall hides in the component tree: a child that awaits can’t start until its parent has rendered. Server Components can be async and await data directly, which is clean — but if a parent awaits, renders, and only then renders a child that awaits, the child’s request starts late. Hoist independent fetches to a common ancestor and start them in parallel, or render sibling async components so React can work them concurrently.

// waterfall: Profile awaits, THEN renders Feed which awaits
async function Profile({ id }: { id: string }) {
  const user = await getUser(id);            // round trip 1
  return <><Header user={user} /><Feed id={id} /></>; // Feed's fetch starts only now
}

// flattened: start both up front, hand promises down, let Suspense stream each in
function Profile({ id }: { id: string }) {
  const userP = getUser(id);                 // both in flight immediately
  const feedP = getFeed(id);
  return (
    <>
      <Suspense fallback={<HeaderSkeleton />}><Header userP={userP} /></Suspense>
      <Suspense fallback={<FeedSkeleton />}><Feed feedP={feedP} /></Suspense>
    </>
  );
}

Passing the promise down (and reading it with use inside each child) lets both requests start at the same instant while each section streams in independently behind its own Suspense boundary.

Prefetch likely-next data so the round trip is already done when the user asks. If you can predict the next view — a row the user is hovering, the route their cursor is on, the tab they’ll open — start its request early instead of waiting for the click. With a server-state cache (TanStack Query, RSC route prefetch) the fetched data is warm by the time navigation happens, turning a visible spinner into an instant render.

// warm the cache on hover; the click then reads from cache, no waterfall
function UserRow({ id }: { id: string }) {
  const qc = useQueryClient();
  return (
    <a
      href={`/users/${id}`}
      onMouseEnter={() => qc.prefetchQuery({ queryKey: ["user", id], queryFn: () => fetchUser(id) })}
    >
      View
    </a>
  );
}

Prefetch is latency hidden ahead of time rather than shrunk. But it spends bandwidth and server work on a guess — so prefetch only what’s likely next (the hovered row, the adjacent route), never everything on the page. Over-prefetching is its own performance bug, covered below.