{data}
}
```
**Correct — resolve outside, pass the value:**
```tsx
async function Parent() {
const value = await getDynamicValue()
return {value}
}
```
**Key rules:**
- Never call `cookies()`, `headers()`, or read `searchParams` inside a `"use cache"` block — read them in a parent component and pass as serializable arguments.
- Every argument passed to a cached function becomes part of the cache key. Include user-identifying values (userId, token) to prevent cross-user data leaks.
- Do not `await` dynamic Promises inside `"use cache"` — resolve them outside and pass the result.
- Nested `"use cache"` functions have isolated scopes; `React.cache` values from an outer function are not visible in an inner one. Cache at the appropriate level and compose via `children`.
- Use `cacheTag()` with user-scoped tags (e.g., `user-$\{userId\}`) to enable targeted invalidation.
Reference: first-party `next-cache-components` / `vercel:next-cache-components` skill (constraints, pitfalls); house scars: `references/ork-delta.md`
### Minimize RSC client boundaries to avoid shipping unnecessary JavaScript to the browser — CRITICAL
## RSC: Client Boundaries
The `'use client'` directive marks the boundary between Server and Client component trees. Every component imported by a Client Component becomes a Client Component too. Push `'use client'` to the smallest interactive leaf components to keep the server-rendered surface area as large as possible.
**Incorrect:**
```tsx
// app/products/page.tsx
'use client' // Entire page is now a client component
import { useState, useEffect } from 'react'
export default function ProductsPage() {
const [products, setProducts] = useState([])
useEffect(() => {
fetch('/api/products').then(r => r.json()).then(setProducts)
}, [])
return (
Products
Products
{title}
{body}
{title}
{body}
Width: {width}px
} ``` **Correct — browser API in useEffect with state:** ```tsx 'use client' import { useState, useEffect } from 'react' function ScreenWidth() { const [width, setWidth] = useState(0) useEffect(() => { const handleResize = () => setWidth(window.innerWidth) handleResize() window.addEventListener('resize', handleResize) return () => window.removeEventListener('resize', handleResize) }, []) returnWidth: {width}px
} ``` **Key rules:** - Never access `window`, `document`, `navigator`, `localStorage`, or other browser APIs during render — always use `useEffect`. - Avoid non-deterministic expressions (`Date.now()`, `Math.random()`, `crypto.randomUUID()`) in JSX — initialize as `null` and set in `useEffect`. - Use `suppressHydrationWarning` only for intentional, harmless mismatches — never to silence bugs. - For components that depend entirely on browser APIs, use a `ClientOnly` wrapper (mount guard via `useEffect`) or `next/dynamic` with `ssr: false`. Reference: first-party `next-best-practices` / `vercel:nextjs` skill (hydration); react.dev hydration-mismatch docs ### Pass only serializable props across the RSC server-client boundary to avoid runtime errors — CRITICAL ## RSC: Serialization Only serializable data can cross the Server-to-Client Component boundary. React must serialize props into the RSC payload sent over the wire. Passing non-serializable values causes build or runtime errors. **Incorrect:** ```tsx // app/dashboard/page.tsx — Server Component export default async function Dashboard() { const data = await getData() return ({item.name}
{isActive ? 'Active' : 'Inactive'}
{optimisticAnalyses.map(analysis => (
)
}
```
---
## Pattern 3: useActionState for Form Handling
### React 19 Form Actions (Without Server Actions)
```tsx
import { useActionState, use } from 'react'
import { z } from 'zod'
const UrlSchema = z.object({
url: z.url('Please enter a valid URL'),
})
async function submitUrl(
prevState: { error: string | null; success: boolean },
formData: FormData
) {
const result = UrlSchema.safeParse({ url: formData.get('url') })
if (!result.success) {
return { error: result.error.errors[0].message, success: false }
}
try {
await api.post('/api/v1/analyses', { url: result.data.url })
return { error: null, success: true }
} catch (error) {
return { error: 'Failed to start analysis', success: false }
}
}
export function UrlInputForm() {
const [state, formAction, isPending] = useActionState(submitUrl, {
error: null,
success: false,
})
return (
)
}
```
---
## Pattern 4: use() Hook for Promise Handling
### Suspense-Based Data Fetching in Client Components
```tsx
import { use, Suspense } from 'react'
// Cache the promise at module level or use a query cache
const analysisPromise = fetchAnalysis(analysisId)
function AnalysisDetails({ analysisId }: { analysisId: string }) {
// ★ use() unwraps promises in render, works with Suspense
const analysis = use(analysisPromise)
return (
{analysis.title}
Status: {analysis.status}
{analysis.title}
}
```
---
## Pattern 5: Prefetching Strategy
### Intent-Based Preloading
```tsx
// hooks/usePrefetch.ts
import { useQueryClient } from '@tanstack/react-query'
import { useRouter } from '@tanstack/react-router'
import { useCallback } from 'react'
export function usePrefetch() {
const queryClient = useQueryClient()
const router = useRouter()
const prefetchAnalysis = useCallback((analysisId: string) => {
// Prefetch route data
router.preloadRoute({
to: '/analyze/$analysisId',
params: { analysisId },
})
// Prefetch query data
queryClient.prefetchQuery({
queryKey: ['analysis', analysisId],
queryFn: () => fetchAnalysis(analysisId),
staleTime: 5 * 60 * 1000,
})
}, [queryClient, router])
return { prefetchAnalysis }
}
// Usage in component
function SkillCard({ skill }) {
const { prefetchAnalysis } = usePrefetch()
return (
prefetchAnalysis(skill.id)}
>
{skill.title}
)
}
```
---
## Pattern 6: Exhaustive Type Checking
### assertNever for Type-Safe Switch Statements
```tsx
// lib/utils.ts
export function assertNever(value: never, message?: string): never {
throw new Error(message ?? `Unexpected value: ${JSON.stringify(value)}`)
}
// Usage in component
type AnalysisStatus = 'pending' | 'analyzing' | 'complete' | 'failed'
function StatusBadge({ status }: { status: AnalysisStatus }) {
switch (status) {
case 'pending':
return
{virtualizer.getVirtualItems().map((virtualItem) => (
{renderItem(items[virtualItem.index])}
))}