next.orly.dev/.claude/skills/react/references/server-components.md

React Server Components & Server Functions

Overview

React Server Components (RSC) allow components to render on the server, improving performance and enabling direct data access. Server Functions allow client components to call server-side functions.

Server Components

What are Server Components?

Components that run only on the server:

• Can access databases directly
• Zero bundle size (code stays on server)
• Better performance (less JavaScript to client)
• Automatic code splitting

Creating Server Components

// app/products/page.tsx
// Server Component by default in App Router

import { db } from '@/lib/db'

const ProductsPage = async () => {
  // Direct database access
  const products = await db.product.findMany({
    where: { active: true },
    include: { category: true }
  })
  
  return (
    <div>
      <h1>Products</h1>
      {products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  )
}

export default ProductsPage

Server Component Rules

Can do:

• Access databases and APIs directly
• Use server-only modules (fs, path, etc.)
• Keep secrets secure (API keys, tokens)
• Reduce client bundle size
• Use async/await at top level

Cannot do:

• Use hooks (useState, useEffect, etc.)
• Use browser APIs (window, document)
• Attach event handlers (onClick, etc.)
• Use Context

Mixing Server and Client Components

// Server Component (default)
const Page = async () => {
  const data = await fetchData()
  
  return (
    <div>
      <ServerComponent data={data} />
      {/* Client component for interactivity */}
      <ClientComponent initialData={data} />
    </div>
  )
}

// Client Component
'use client'

import { useState } from 'react'

const ClientComponent = ({ initialData }) => {
  const [count, setCount] = useState(0)
  
  return (
    <button onClick={() => setCount(c => c + 1)}>
      {count}
    </button>
  )
}

Server Component Patterns

Data Fetching

// app/user/[id]/page.tsx
interface PageProps {
  params: { id: string }
}

const UserPage = async ({ params }: PageProps) => {
  const user = await db.user.findUnique({
    where: { id: params.id }
  })
  
  if (!user) {
    notFound()  // Next.js 404
  }
  
  return <UserProfile user={user} />
}

Parallel Data Fetching

const DashboardPage = async () => {
  // Fetch in parallel
  const [user, orders, stats] = await Promise.all([
    fetchUser(),
    fetchOrders(),
    fetchStats()
  ])
  
  return (
    <>
      <UserHeader user={user} />
      <OrdersList orders={orders} />
      <StatsWidget stats={stats} />
    </>
  )
}

Streaming with Suspense

const Page = () => {
  return (
    <>
      <Header />
      <Suspense fallback={<ProductsSkeleton />}>
        <Products />
      </Suspense>
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews />
      </Suspense>
    </>
  )
}

const Products = async () => {
  const products = await fetchProducts()  // Slow query
  return <ProductsList products={products} />
}

Server Functions (Server Actions)

What are Server Functions?

Functions that run on the server but can be called from client components:

• Marked with 'use server' directive
• Can mutate data
• Integrated with forms
• Type-safe with TypeScript

Creating Server Functions

File-level directive

// app/actions.ts
'use server'

import { db } from '@/lib/db'
import { revalidatePath } from 'next/cache'

export async function createProduct(formData: FormData) {
  const name = formData.get('name') as string
  const price = Number(formData.get('price'))
  
  const product = await db.product.create({
    data: { name, price }
  })
  
  revalidatePath('/products')
  return product
}

export async function deleteProduct(id: string) {
  await db.product.delete({ where: { id } })
  revalidatePath('/products')
}

Function-level directive

// Inside a Server Component
const MyComponent = async () => {
  async function handleSubmit(formData: FormData) {
    'use server'
    const email = formData.get('email') as string
    await saveEmail(email)
  }
  
  return <form action={handleSubmit}>...</form>
}

Using Server Functions

With Forms

'use client'

import { createProduct } from './actions'

const ProductForm = () => {
  return (
    <form action={createProduct}>
      <input name="name" required />
      <input name="price" type="number" required />
      <button type="submit">Create</button>
    </form>
  )
}

With useActionState

'use client'

import { useActionState } from 'react'
import { createProduct } from './actions'

type FormState = {
  message: string
  success: boolean
} | null

const ProductForm = () => {
  const [state, formAction, isPending] = useActionState<FormState>(
    async (previousState, formData: FormData) => {
      try {
        await createProduct(formData)
        return { message: 'Product created!', success: true }
      } catch (error) {
        return { message: 'Failed to create product', success: false }
      }
    },
    null
  )
  
  return (
    <form action={formAction}>
      <input name="name" required />
      <input name="price" type="number" required />
      <button disabled={isPending}>
        {isPending ? 'Creating...' : 'Create'}
      </button>
      {state?.message && (
        <p className={state.success ? 'text-green-600' : 'text-red-600'}>
          {state.message}
        </p>
      )}
    </form>
  )
}

Programmatic Invocation

'use client'

import { deleteProduct } from './actions'

const DeleteButton = ({ productId }: { productId: string }) => {
  const [isPending, setIsPending] = useState(false)
  
  const handleDelete = async () => {
    setIsPending(true)
    try {
      await deleteProduct(productId)
    } catch (error) {
      console.error(error)
    } finally {
      setIsPending(false)
    }
  }
  
  return (
    <button onClick={handleDelete} disabled={isPending}>
      {isPending ? 'Deleting...' : 'Delete'}
    </button>
  )
}

Server Function Patterns

Validation with Zod

'use server'

import { z } from 'zod'

const ProductSchema = z.object({
  name: z.string().min(3),
  price: z.number().positive(),
  description: z.string().optional()
})

export async function createProduct(formData: FormData) {
  const rawData = {
    name: formData.get('name'),
    price: Number(formData.get('price')),
    description: formData.get('description')
  }
  
  // Validate
  const result = ProductSchema.safeParse(rawData)
  if (!result.success) {
    return { 
      success: false, 
      errors: result.error.flatten().fieldErrors 
    }
  }
  
  // Create product
  const product = await db.product.create({
    data: result.data
  })
  
  revalidatePath('/products')
  return { success: true, product }
}

Authentication Check

'use server'

import { auth } from '@/lib/auth'
import { redirect } from 'next/navigation'

export async function createOrder(formData: FormData) {
  const session = await auth()
  
  if (!session?.user) {
    redirect('/login')
  }
  
  const order = await db.order.create({
    data: {
      userId: session.user.id,
      // ... other fields
    }
  })
  
  return order
}

Error Handling

'use server'

export async function updateProfile(formData: FormData) {
  try {
    const userId = await getCurrentUserId()
    
    const profile = await db.user.update({
      where: { id: userId },
      data: {
        name: formData.get('name') as string,
        bio: formData.get('bio') as string
      }
    })
    
    revalidatePath('/profile')
    return { success: true, profile }
  } catch (error) {
    console.error('Failed to update profile:', error)
    return { 
      success: false, 
      error: 'Failed to update profile. Please try again.' 
    }
  }
}

Optimistic Updates

'use client'

import { useOptimistic } from 'react'
import { likePost } from './actions'

const Post = ({ post }: { post: Post }) => {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    post.likes,
    (currentLikes) => currentLikes + 1
  )
  
  const handleLike = async () => {
    addOptimisticLike(null)
    await likePost(post.id)
  }
  
  return (
    <div>
      <p>{post.content}</p>
      <button onClick={handleLike}>
        ❤️ {optimisticLikes}
      </button>
    </div>
  )
}

Data Mutations & Revalidation

revalidatePath

Invalidate cached data for a path:

'use server'

import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  await db.post.create({ data: {...} })
  
  // Revalidate the posts page
  revalidatePath('/posts')
  
  // Revalidate with layout
  revalidatePath('/posts', 'layout')
}

revalidateTag

Invalidate cached data by tag:

'use server'

import { revalidateTag } from 'next/cache'

export async function updateProduct(id: string, data: ProductData) {
  await db.product.update({ where: { id }, data })
  
  // Revalidate all queries tagged with 'products'
  revalidateTag('products')
}

redirect

Redirect after mutation:

'use server'

import { redirect } from 'next/navigation'

export async function createPost(formData: FormData) {
  const post = await db.post.create({ data: {...} })
  
  // Redirect to the new post
  redirect(`/posts/${post.id}`)
}

Caching with Server Components

cache Function

Deduplicate requests within a render:

import { cache } from 'react'

export const getUser = cache(async (id: string) => {
  return await db.user.findUnique({ where: { id } })
})

// Called multiple times but only fetches once per render
const Page = async () => {
  const user1 = await getUser('123')
  const user2 = await getUser('123')  // Uses cached result
  
  return <div>...</div>
}

Next.js fetch Caching

// Cached by default
const data = await fetch('https://api.example.com/data')

// Revalidate every 60 seconds
const data = await fetch('https://api.example.com/data', {
  next: { revalidate: 60 }
})

// Never cache
const data = await fetch('https://api.example.com/data', {
  cache: 'no-store'
})

// Tag for revalidation
const data = await fetch('https://api.example.com/data', {
  next: { tags: ['products'] }
})

Best Practices

1. Component Placement

• Keep interactive components client-side
• Use server components for data fetching
• Place 'use client' as deep as possible in tree

2. Data Fetching

• Fetch in parallel when possible
• Use Suspense for streaming
• Cache expensive operations

3. Server Functions

• Validate all inputs
• Check authentication/authorization
• Handle errors gracefully
• Return serializable data only

4. Performance

• Minimize client JavaScript
• Use streaming for slow queries
• Implement proper caching
• Optimize database queries

5. Security

• Never expose secrets to client
• Validate server function inputs
• Use environment variables
• Implement rate limiting

Common Patterns

Layout with Dynamic Data

// app/layout.tsx
const RootLayout = async ({ children }: { children: React.ReactNode }) => {
  const user = await getCurrentUser()
  
  return (
    <html>
      <body>
        <Header user={user} />
        {children}
        <Footer />
      </body>
    </html>
  )
}

Loading States

// app/products/loading.tsx
export default function Loading() {
  return <ProductsSkeleton />
}

// app/products/page.tsx
const ProductsPage = async () => {
  const products = await fetchProducts()
  return <ProductsList products={products} />
}

Error Boundaries

// app/products/error.tsx
'use client'

export default function Error({
  error,
  reset
}: {
  error: Error
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <p>{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  )
}

Search with Server Functions

'use client'

import { searchProducts } from './actions'
import { useDeferredValue, useState, useEffect } from 'react'

const SearchPage = () => {
  const [query, setQuery] = useState('')
  const [results, setResults] = useState([])
  const deferredQuery = useDeferredValue(query)
  
  useEffect(() => {
    if (deferredQuery) {
      searchProducts(deferredQuery).then(setResults)
    }
  }, [deferredQuery])
  
  return (
    <>
      <input 
        value={query} 
        onChange={e => setQuery(e.target.value)}
      />
      <ResultsList results={results} />
    </>
  )
}

Troubleshooting

Common Issues

1. "Cannot use hooks in Server Component"

   • Add 'use client' directive
   • Move state logic to client component

2. "Functions cannot be passed to Client Components"

   • Use Server Functions instead
   • Pass data, not functions

3. Hydration mismatches

   • Ensure server and client render same HTML
   • Use useEffect for browser-only code

4. Slow initial load

   • Implement Suspense boundaries
   • Use streaming rendering
   • Optimize database queries

References

• React Server Components: https://react.dev/reference/rsc/server-components
• Server Functions: https://react.dev/reference/rsc/server-functions
• Next.js App Router: https://nextjs.org/docs/app