Streaming SSR and Suspense Guide

# Streaming SSR and Suspense Guide

Leverage React Suspense and streaming server-side rendering in your Google Antigravity applications for superior loading experiences. This guide covers loading states, parallel data fetching, and streaming patterns.

## Suspense with Server Components

Use Suspense to stream content progressively:

```typescript
// app/prompts/page.tsx
import { Suspense } from "react";
import { PromptsList } from "@/components/PromptsList";
import { PromptsListSkeleton } from "@/components/skeletons/PromptsListSkeleton";
import { CategoryFilter } from "@/components/CategoryFilter";
import { CategoryFilterSkeleton } from "@/components/skeletons/CategoryFilterSkeleton";

export default function PromptsPage() {
  return (
    <div className="container py-8">
      <h1 className="text-3xl font-bold mb-8">All Prompts</h1>
      
      <div className="flex gap-8">
        {/* Sidebar loads independently */}
        <aside className="w-64">
          <Suspense fallback={<CategoryFilterSkeleton />}>
            <CategoryFilter />
          </Suspense>
        </aside>
        
        {/* Main content streams separately */}
        <main className="flex-1">
          <Suspense fallback={<PromptsListSkeleton count={12} />}>
            <PromptsList />
          </Suspense>
        </main>
      </div>
    </div>
  );
}
```

## Loading UI Components

Create skeleton components for loading states:

```typescript
// components/skeletons/PromptsListSkeleton.tsx
export function PromptsListSkeleton({ count = 6 }: { count?: number }) {
  return (
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
      {Array.from({ length: count }).map((_, i) => (
        <div
          key={i}
          className="rounded-lg border border-gray-200 p-6 animate-pulse"
        >
          <div className="h-6 bg-gray-200 rounded w-3/4 mb-4" />
          <div className="h-4 bg-gray-200 rounded w-full mb-2" />
          <div className="h-4 bg-gray-200 rounded w-5/6 mb-4" />
          <div className="flex gap-2">
            <div className="h-6 bg-gray-200 rounded-full w-16" />
            <div className="h-6 bg-gray-200 rounded-full w-20" />
          </div>
        </div>
      ))}
    </div>
  );
}

// components/skeletons/CategoryFilterSkeleton.tsx
export function CategoryFilterSkeleton() {
  return (
    <div className="space-y-2">
      <div className="h-8 bg-gray-200 rounded w-24 mb-4" />
      {Array.from({ length: 8 }).map((_, i) => (
        <div
          key={i}
          className="h-10 bg-gray-200 rounded animate-pulse"
          style={{ animationDelay: `${i * 100}ms` }}
        />
      ))}
    </div>
  );
}
```

## Parallel Data Fetching

Fetch data in parallel with Suspense:

```typescript
// app/dashboard/page.tsx
import { Suspense } from "react";

// Each component fetches its own data
async function UserStats() {
  const stats = await fetchUserStats(); // Runs in parallel
  return <StatsDisplay stats={stats} />;
}

async function RecentActivity() {
  const activity = await fetchRecentActivity(); // Runs in parallel
  return <ActivityFeed activity={activity} />;
}

async function Notifications() {
  const notifications = await fetchNotifications(); // Runs in parallel
  return <NotificationList notifications={notifications} />;
}

export default function Dashboard() {
  return (
    <div className="grid grid-cols-12 gap-6">
      {/* All three sections load independently and in parallel */}
      <div className="col-span-8">
        <Suspense fallback={<StatsSkeleton />}>
          <UserStats />
        </Suspense>
        
        <Suspense fallback={<ActivitySkeleton />}>
          <RecentActivity />
        </Suspense>
      </div>
      
      <div className="col-span-4">
        <Suspense fallback={<NotificationsSkeleton />}>
          <Notifications />
        </Suspense>
      </div>
    </div>
  );
}
```

## Loading.tsx Conventions

Use Next.js loading conventions:

```typescript
// app/prompts/loading.tsx
export default function Loading() {
  return (
    <div className="container py-8">
      <div className="h-10 bg-gray-200 rounded w-48 mb-8 animate-pulse" />
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
        {Array.from({ length: 12 }).map((_, i) => (
          <div
            key={i}
            className="h-48 bg-gray-200 rounded-lg animate-pulse"
          />
        ))}
      </div>
    </div>
  );
}
```

## Streaming with use Hook

Stream data with the experimental use hook:

```typescript
// components/StreamedContent.tsx
"use client";

import { use, Suspense } from "react";

function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise);
  return <div>{data.content}</div>;
}

export function StreamedContent() {
  const dataPromise = fetchData(); // Returns promise immediately

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <DataDisplay dataPromise={dataPromise} />
    </Suspense>
  );
}
```

## Best Practices

1. **Strategic Boundaries**: Place Suspense at logical content boundaries
2. **Skeleton Matching**: Make skeletons match actual content dimensions
3. **Progressive Loading**: Stream most important content first
4. **Parallel Fetching**: Let independent data load simultaneously
5. **Error Boundaries**: Combine with error boundaries for resilience
6. **Loading Indicators**: Use subtle animations to indicate activity