...
}
```
**Push "use client" as far down the tree as possible.** The boundary should be at the leaf, not the root.
---
## Phase 2: Data Fetching & Caching
### Data Fetching Hierarchy (Prefer Top โ Bottom)
1. **Server Component direct fetch** โ simplest, most performant
2. **Server Actions** โ for mutations and form submissions
3. **Route Handlers** โ for webhooks, external API endpoints
4. **Client-side fetch (SWR/React Query)** โ for real-time/polling data only
### Fetch Configuration
```tsx
// Static data (cached indefinitely, revalidated on deploy)
const data = await fetch('https://api.example.com/data', {
cache: 'force-cache' // Default in App Router
})
// Revalidate every hour
const data = await fetch('https://api.example.com/data', {
next: { revalidate: 3600 }
})
// Always fresh (no cache)
const data = await fetch('https://api.example.com/data', {
cache: 'no-store'
})
// Tag-based revalidation
const data = await fetch('https://api.example.com/products', {
next: { tags: ['products'] }
})
// Then in a Server Action:
import { revalidateTag } from 'next/cache'
revalidateTag('products')
```
### Caching Strategy by Data Type
| Data Type | Cache Strategy | Revalidate | Tags |
|-----------|---------------|------------|------|
| CMS content | ISR | 3600s (1h) | `['cms', 'posts']` |
| Product catalog | ISR | 300s (5m) | `['products']` |
| User profile | No cache | โ | โ |
| Pricing/inventory | No cache | โ | โ |
| Static assets | Force cache | On deploy | โ |
| Analytics/dashboards | ISR | 60s | `['analytics']` |
| Auth tokens | No cache | โ | โ |
### Database Queries (No fetch API)
```tsx
import { unstable_cache } from 'next/cache'
import { db } from '@/lib/db'
// Cache database queries with tags
const getProducts = unstable_cache(
async (categoryId: string) => {
return db.query.products.findMany({
where: eq(products.categoryId, categoryId)
})
},
['products'], // Cache key parts
{
revalidate: 300,
tags: ['products']
}
)
```
### Parallel Data Fetching
```tsx
// โ
CORRECT: Parallel fetches
export default async function DashboardPage() {
const [user, stats, notifications] = await Promise.all([
getUser(),
getStats(),
getNotifications()
])
return
Dashboard
{/* Fast: renders immediately */}
{/* Slow: streams in when ready */}
}>
{/* Async Server Component */}
}>
)
}
```
---
## Phase 3: Server Actions & Mutations
### Server Action Best Practices
```tsx
// actions/user.ts
'use server'
import { z } from 'zod'
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
const updateProfileSchema = z.object({
name: z.string().min(1).max(100),
email: z.string().email(),
bio: z.string().max(500).optional()
})
export async function updateProfile(formData: FormData) {
// 1. Authenticate
const session = await getSession()
if (!session) throw new Error('Unauthorized')
// 2. Validate
const parsed = updateProfileSchema.safeParse({
name: formData.get('name'),
email: formData.get('email'),
bio: formData.get('bio')
})
if (!parsed.success) {
return { error: parsed.error.flatten().fieldErrors }
}
// 3. Authorize
if (session.userId !== formData.get('userId')) {
throw new Error('Forbidden')
}
// 4. Mutate
await db.update(users)
.set(parsed.data)
.where(eq(users.id, session.userId))
// 5. Revalidate
revalidatePath('/profile')
return { success: true }
}
```
### Server Action Rules
1. **Always validate input** โ FormData is user input, never trust it
2. **Always check auth** โ Server Actions are public endpoints
3. **Always check authorization** โ user can only modify their own data
4. **Use Zod for validation** โ type-safe, composable schemas
5. **Return errors, don't throw** โ throwing shows error boundary, returning shows inline errors
6. **Revalidate after mutations** โ `revalidatePath` or `revalidateTag`
7. **Never return sensitive data** โ return only what the client needs
### useActionState Pattern (React 19)
```tsx
'use client'
import { useActionState } from 'react'
import { updateProfile } from '@/actions/user'
export function ProfileForm({ user }: { user: User }) {
const [state, action, pending] = useActionState(updateProfile, null)
return (