Prepared Docs

Prepared Docs

⌘K

    Loading navigation…

User

  1. Performance
  3. Eliminating Waterfalls

Eliminating Waterfalls

Async optimization patterns to eliminate sequential delays.

Quick Reference

CRITICAL priority - Waterfalls are the #1 performance killer.

Key patterns:

  • Use Promise.all() for independent operations (2-10× improvement)
  • Defer await into branches where actually used
  • Start promises early, await late
  • Use Suspense boundaries for streaming (Next.js)

What Are Waterfalls?

Waterfalls occur when async operations run sequentially instead of in parallel. Each sequential await adds full network latency.

Promise.all() for Independent Operations

When operations have no interdependencies, execute concurrently:

Apollo Client Parallel Queries

Multiple useQuery hooks run in parallel automatically:

Defer Await into Branches

Move await into branches where actually used:

Early Returns

Start Promises Early, Await Late

Suspense Boundaries (Next.js)

Use Suspense to stream content:

Common Patterns

Loading Dashboard Data

With Conditional Logic

Measuring Impact

Use browser DevTools Performance tab to identify waterfalls:

  1. Record a page load
  2. Look for sequential network requests
  3. Check if requests could run in parallel
  4. Refactor to use Promise.all() or Suspense

Before optimization:

After optimization:

Related Documentation

  • Bundle Optimization - Code splitting patterns
  • Writing Hooks - Async patterns in hooks
  • GraphQL Operations - Parallel queries

Reference Files

For more detailed technical guidance, see these reference files:

  • async-defer-await.md
  • async-parallel.md
  • async-suspense-boundaries.md

Previous

Overview / Project Structure

Next

Performance / Bundle Optimization

On this page

Quick Reference
What Are Waterfalls?
Promise.all() for Independent Operations
Apollo Client Parallel Queries
Defer Await into Branches
Early Returns
Start Promises Early, Await Late
Suspense Boundaries (Next.js)
Common Patterns
Loading Dashboard Data
With Conditional Logic
Measuring Impact
Related Documentation
Reference Files