Streaming & Suspense

How Streaming Works

Next.js streams Server Component output as HTML in chunks. The shell — layouts, static content, Suspense fallbacks — arrives first. Slow data sections stream when ready without blocking the entire page.

This improves Time to First Byte perception and Largest Contentful Paint when structured correctly. Users interact with loaded sections while others still fetch.

• HTML streams in chunks
• Shell arrives before slow data
• Improves perceived performance

Suspense Boundaries

Wrap async Server Components in `<Suspense fallback={<Skeleton />}>`. Each boundary streams independently — multiple boundaries on one page allow parallel streaming of unrelated slow sections.

loading.tsx is route-level Suspense fallback automatically applied to page content. Nested loading.tsx files in subfolders scope fallbacks to those segments.

• Suspense wraps async server components
• Multiple boundaries stream in parallel
• loading.tsx is automatic route Suspense

<Suspense fallback={<PostsSkeleton />}>
  <Posts />
</Suspense>

Avoiding Waterfalls in Streaming

Sequential Suspense boundaries nested unnecessarily create waterfalls — outer must resolve before inner starts. Prefer sibling Suspense boundaries at the same level for parallel streaming.

Start fetches high in the tree but await low in the component that renders data — pass promises as props to child Suspense boundaries (preload pattern) so fetch begins before child Suspense renders.

• Sibling Suspense for parallelism
• Preload pattern starts fetch early
• Avoid nested sequential boundaries

Streaming with Client Components

Server streams HTML containing client component placeholders. Client JavaScript hydrates interactive islands after stream completes relevant sections. Heavy client bundles delay hydration — keep client boundaries small.

React 18 selective hydration prioritizes interactive components user is likely to engage with first.

• Client placeholders in streamed HTML
• Small client boundaries hydrate faster
• Selective hydration prioritizes interaction

Monitoring Streaming Performance

Measure with Web Vitals — LCP should improve when hero content is outside slow Suspense boundaries. TTFB may increase slightly for first byte of shell vs blocking render — net UX usually wins.

Log slow server component render times in production. Alerts on P95 segment render duration help identify queries blocking stream completion.

• Hero content outside slow boundaries
• Monitor segment render P95
• Balance TTFB vs progressive display