React Server Components Framework

Overview

React Server Components (RSC) represent a paradigm shift in React architecture, enabling server-first rendering with client-side interactivity. This skill provides comprehensive patterns, templates, and best practices for building modern Next.js 15 applications using the App Router with Server Components, Server Actions, and streaming.

When to use this skill:
- Building Next.js 15+ applications with the App Router
- Designing component boundaries (Server vs Client Components)
- Implementing data fetching with caching and revalidation
- Creating mutations with Server Actions
- Optimizing performance with streaming and Suspense
- Implementing Partial Prerendering (PPR)
- Designing advanced routing patterns (parallel, intercepting routes)

Why React Server Components Matter

RSC fundamentally changes how we think about React applications:

• Server-First Architecture: Components render on the server by default, reducing client bundle size
• Zero Client Bundle: Server Components don't ship JavaScript to the client
• Direct Backend Access: Access databases, file systems, and APIs directly from components
• Automatic Code Splitting: Only Client Components and their dependencies are bundled
• Streaming & Suspense: Progressive rendering for instant perceived performance
• Type-Safe Data Fetching: End-to-end TypeScript from database to UI
• SEO & Performance: Server rendering improves Core Web Vitals and SEO

Core Concepts

1. Server Components vs Client Components

Server Components (default):
- Can be async and use await
- Direct database access
- Cannot use hooks or browser APIs
- Zero client JavaScript

Client Components (with 'use client'):
- Can use hooks (useState, useEffect, etc.)
- Browser APIs available
- Cannot be async
- Ships JavaScript to client

Key Rule: Server Components can render Client Components, but Client Components cannot directly import Server Components (use children prop instead).

Detailed Patterns: See references/component-patterns.md for:
- Complete component boundary rules
- Composition patterns
- Props passing strategies
- Common pitfalls and solutions

2. Data Fetching

Next.js extends the fetch API with powerful caching and revalidation:

// Static (cached indefinitely)
await fetch(url, { cache: 'force-cache' })

// Revalidate every 60 seconds
await fetch(url, { next: { revalidate: 60 } })

// Always fresh
await fetch(url, { cache: 'no-store' })

// Tag-based revalidation
await fetch(url, { next: { tags: ['posts'] } })

Patterns:
- Parallel fetching: Promise.all([fetch1, fetch2, fetch3])
- Sequential fetching: When data depends on previous results
- Route segment config: Control static/dynamic rendering

Detailed Implementation: See references/data-fetching.md for:
- Complete caching strategies
- Revalidation methods (revalidatePath, revalidateTag)
- Database queries in Server Components
- generateStaticParams for SSG
- Error handling patterns

3. Server Actions

Server Actions enable mutations without API routes:

// app/actions.ts
'use server'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  const post = await db.post.create({ data: { title } })

  revalidatePath('/posts')
  redirect(`/posts/${post.id}`)
}

Progressive Enhancement: Forms work without JavaScript, then enhance with client-side states.

Detailed Implementation: See references/server-actions.md for:
- Progressive enhancement patterns
- useFormStatus and useActionState hooks (React 19)
- Optimistic UI with useOptimistic + useTransition
- Validation with Zod
- Inline vs exported Server Actions

4. Streaming with Suspense

Stream components independently for better perceived performance:

import { Suspense } from 'react'

export default function Dashboard() {
  return (
    <div>
      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />
      </Suspense>

      <Suspense fallback={<InvoicesSkeleton />}>
        <LatestInvoices />
      </Suspense>
    </div>
  )
}

Benefits:
- Show content as it's ready
- Non-blocking data fetching
- Better Core Web Vitals

Templates: Use templates/ServerComponent.tsx for streaming patterns

5. Advanced Routing

Parallel Routes: Render multiple pages simultaneously

app/
  @team/page.tsx
  @analytics/page.tsx
  layout.tsx  # Receives both as props

Intercepting Routes: Show modals while preserving URLs

app/
  photos/[id]/page.tsx      # Direct route
  (..)photos/[id]/page.tsx  # Intercepted (modal)

Partial Prerendering (PPR): Mix static and dynamic content

export const experimental_ppr = true

// Static shell + dynamic Suspense boundaries

Detailed Implementation: See references/routing-patterns.md for:
- Parallel routes layout implementation
- Intercepting routes for modals
- PPR configuration and patterns
- Route groups for organization
- Dynamic, catch-all, and optional catch-all routes

Searching References

Use grep to find specific patterns in references:

# Find component patterns
grep -r "Server Component" references/

# Search for data fetching strategies
grep -A 10 "Caching Strategies" references/data-fetching.md

# Find Server Actions examples
grep -B 5 "Progressive Enhancement" references/server-actions.md

# Locate routing patterns
grep -n "Parallel Routes" references/routing-patterns.md

# Search migration guide
grep -i "pages router\|getServerSideProps" references/migration-guide.md

React 19 Patterns (2025+)

React 19 introduces significant changes to component patterns. This section covers the modernization requirements.

Detailed Implementation: See references/react-19-patterns.md for:
- Complete migration guide from React 18
- Code transformation examples
- Testing patterns for React 19 hooks

1. Function Declarations over React.FC

React 19 deprecates React.FC because it no longer includes children in props by default. Always use function declarations:

// ❌ DEPRECATED (React 18 pattern)
export const Button: React.FC<ButtonProps> = ({ children, onClick }) => {
  return <button onClick={onClick}>{children}</button>
}

// ✅ RECOMMENDED (React 19 pattern)
export function Button({ children, onClick }: ButtonProps): React.ReactNode {
  return <button onClick={onClick}>{children}</button>
}

// ✅ ALSO VALID (arrow function without React.FC)
export const Button = ({ children, onClick }: ButtonProps): React.ReactNode => {
  return <button onClick={onClick}>{children}</button>
}

Benefits:
- Simpler type inference
- Explicit children in props when needed
- Better tree-shaking
- Clearer component signatures

2. Ref as Prop (Removal of forwardRef)

React 19 removes the need for forwardRef. Refs are now passed as regular props:

// ❌ DEPRECATED (React 18 pattern)
import { forwardRef } from 'react'

const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => {
  return <input ref={ref} {...props} />
})

// ✅ RECOMMENDED (React 19 pattern)
interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  ref?: React.Ref<HTMLInputElement>
}

export function Input({ ref, ...props }: InputProps): React.ReactNode {
  return <input ref={ref} {...props} />
}

Note: For backwards compatibility during migration, you can support both patterns temporarily.

3. useActionState (replaces useFormState)

useActionState is the new API for form state management:

'use client'

import { useActionState } from 'react'

interface FormState {
  message: string
  success: boolean
}

async function submitForm(prevState: FormState, formData: FormData): Promise<FormState> {
  const email = formData.get('email')
  // Process form...
  return { message: 'Submitted!', success: true }
}

export function ContactForm(): React.ReactNode {
  const [state, formAction, isPending] = useActionState(submitForm, {
    message: '',
    success: false
  })

  return (
    <form action={formAction}>
      <input name="email" type="email" disabled={isPending} />
      <SubmitButton />
      {state.message && <p>{state.message}</p>}
    </form>
  )
}

4. useFormStatus for Submit Buttons

'use client'

import { useFormStatus } from 'react-dom'

export function SubmitButton(): React.ReactNode {
  const { pending } = useFormStatus()

  return (
    <button type="submit" disabled={pending} aria-busy={pending}>
      {pending ? 'Submitting...' : 'Submit'}
    </button>
  )
}

5. useOptimistic for Optimistic Updates

'use client'

import { useOptimistic, useTransition } from 'react'

interface Item { id: string; name: string }

export function ItemList({ items }: { items: Item[] }): React.ReactNode {
  const [optimisticItems, addOptimisticItem] = useOptimistic(
    items,
    (state, newItem: Item) => [...state, newItem]
  )
  const [, startTransition] = useTransition()

  const handleAdd = async (item: Item) => {
    startTransition(() => {
      addOptimisticItem(item) // Immediate UI update
    })
    await saveItem(item) // Server mutation (auto-rollback on error)
  }

  return <ul>{optimisticItems.map(i => <li key={i.id}>{i.name}</li>)}</ul>
}

Best Practices

Component Boundary Design

• ✅ Keep Client Components at the edges (leaves) of the component tree
• ✅ Use Server Components by default
• ✅ Extract minimal interactive parts to Client Components
• ✅ Pass Server Components as children to Client Components
• ❌ Avoid making entire pages Client Components

Data Fetching

• ✅ Fetch data in Server Components close to where it's used
• ✅ Use parallel fetching for independent data
• ✅ Set appropriate cache and revalidate options
• ✅ Use generateStaticParams for static routes
• ❌ Don't fetch data in Client Components with useEffect (use Server Components)

Performance

• ✅ Use Suspense boundaries for streaming
• ✅ Implement loading.tsx for instant loading states
• ✅ Enable PPR for static/dynamic mix
• ✅ Optimize images with next/image
• ✅ Use route segment config to control rendering mode

Error Handling

• ✅ Implement error.tsx for error boundaries
• ✅ Use not-found.tsx for 404 pages
• ✅ Handle fetch errors gracefully
• ✅ Validate Server Action inputs

Templates

Use provided templates for common patterns:

• templates/ServerComponent.tsx - Basic async Server Component with data fetching
• templates/ClientComponent.tsx - Interactive Client Component with hooks
• templates/ServerAction.tsx - Server Action with validation and revalidation

Examples

Complete Blog App

See examples/blog-app/ for a full implementation:
- Server Components for post listing and details
- Client Components for comments and likes
- Server Actions for creating/editing posts
- Streaming with Suspense
- Parallel routes for dashboard

Checklists

RSC Implementation Checklist

See checklists/rsc-implementation.md for comprehensive validation covering:
- [ ] Component boundaries properly defined (Server vs Client)
- [ ] Data fetching with appropriate caching strategy
- [ ] Server Actions for mutations
- [ ] Streaming with Suspense for slow components
- [ ] Error handling (error.tsx, not-found.tsx)
- [ ] Loading states (loading.tsx)
- [ ] Metadata API for SEO
- [ ] Route segment config optimized

Common Patterns

Search with URL State

// app/search/page.tsx
export default async function SearchPage({
  searchParams,
}: {
  searchParams: { q?: string }
}) {
  const query = searchParams.q || ''
  const results = query ? await searchProducts(query) : []

  return (
    <div>
      <SearchForm initialQuery={query} />
      <SearchResults results={results} />
    </div>
  )
}

Authentication

import { cookies } from 'next/headers'

export default async function DashboardPage() {
  const token = cookies().get('token')?.value
  const user = await verifyToken(token)

  if (!user) {
    redirect('/login')
  }

  return <Dashboard user={user} />
}

Optimistic UI

'use client'

import { useOptimistic } from 'react'

export function TodoList({ todos }) {
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (state, newTodo) => [...state, newTodo]
  )

  return <ul>{/* render optimisticTodos */}</ul>
}

Migration from Pages Router

Incremental Adoption: Both pages/ and app/ can coexist

Key Changes:
- getServerSideProps → async Server Component
- getStaticProps → async Server Component with caching
- API routes → Server Actions
- _app.tsx → layout.tsx
- <Head> → generateMetadata function

Detailed Migration: See references/migration-guide.md for:
- Step-by-step migration guide
- Before/after code examples
- Common migration pitfalls
- Layout and metadata migration patterns

Troubleshooting

Error: "You're importing a component that needs useState"
- Fix: Add 'use client' directive to the component

Error: "async/await is not valid in non-async Server Components"
- Fix: Add async to function declaration

Error: "Cannot use Server Component inside Client Component"
- Fix: Pass Server Component as children prop instead of importing

Error: "Hydration mismatch"
- Fix: Use 'use client' for components using Date.now(), Math.random(), or browser APIs

Resources

• Next.js 15 Documentation
• React Server Components RFC
• App Router Migration Guide
• Server Actions Documentation

Skill Metadata

Skill Version: 1.4.0
Last Updated: 2025-12-29
Maintained by: AI Agent Hub Team

Changelog

v1.4.0 (2025-12-29)

• Updated blog-app-example.tsx to e-commerce dashboard (Product + Order management)
• All examples now use real-world dashboard/app scenarios
• Updated React 19 patterns with concrete e-commerce types (OrderStatus, Product, etc.)
• Added exhaustive type checking examples with OrderStatus enum
• Updated all "SkillForge" and "project" references to real application examples
• Examples demonstrate: Product catalog, Inventory tracking, Order history, SEO optimization

v1.3.0 (2025-12-27)

• Updated to React 19.2.3 patterns
• Added complete React 19 modernization guide
• Updated all examples to use function declarations (no React.FC)
• Updated to useActionState (replaced useFormState)

v1.2.0 (2025-12-20)

• Added TanStack Router patterns for SPAs
• Added React 19 hooks (use(), useOptimistic, useActionState)
• Added promise caching patterns for use() hook

v1.1.0 (2025-12-15)

• Added comprehensive RSC implementation patterns
• Added Server Actions with progressive enhancement
• Added streaming with Suspense examples

Next Steps

After mastering React Server Components:
1. Explore Streaming API Patterns skill for real-time data
2. Use Type Safety & Validation skill for tRPC integration
3. Apply Edge Computing Patterns skill for global deployment
4. Reference Performance Optimization skill for Core Web Vitals