react-server-components-framework

# 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: ```tsx // 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: ```tsx // 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: ```tsx 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 ```tsx 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: ```bash # 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: ```tsx // ❌ 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: ```tsx // ❌ 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: ```tsx '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 ```tsx '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 ```tsx '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 ```tsx // 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 ```tsx 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 ```tsx '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"**