@codihaus/claude-skills 1.6.18 → 1.6.20

package/knowledge/stacks/nextjs/references/rsc-patterns.md

@@ -0,0 +1,705 @@
+# Next.js RSC & Server Actions Patterns
+
+> Critical patterns for React Server Components and Server Actions from Vercel Engineering
+
+## Eliminating Waterfalls
+
+### Defer Await Until Needed
+
+**Impact**: HIGH - Avoids blocking unused code paths
+
+Move `await` operations into branches where they're actually used:
+
+```typescript
+// ❌ Incorrect: blocks both branches
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+
+  if (skipProcessing) {
+    return { skipped: true }  // Still waited!
+  }
+
+  return processUserData(userData)
+}
+
+// ✅ Correct: only blocks when needed
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    return { skipped: true }  // No wait
+  }
+
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Early return optimization**:
+
+```typescript
+// ❌ Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+
+  if (!resource) return { error: 'Not found' }
+  if (!permissions.canEdit) return { error: 'Forbidden' }
+
+  return await updateResourceData(resource, permissions)
+}
+
+// ✅ Correct: check resource first (cheaper)
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  if (!resource) return { error: 'Not found' }
+
+  const permissions = await fetchPermissions(userId)
+  if (!permissions.canEdit) return { error: 'Forbidden' }
+
+  return await updateResourceData(resource, permissions)
+}
+```
+
+### Dependency-Based Parallelization
+
+**Impact**: CRITICAL - 2-10× improvement
+
+Use `better-all` for partial dependencies:
+
+```typescript
+// ❌ Incorrect: profile waits for config unnecessarily
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+
+// ✅ Correct: config and profile run in parallel
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+### Prevent Waterfall Chains in API Routes
+
+**Impact**: CRITICAL - 2-10× improvement
+
+Start independent operations immediately:
+
+```typescript
+// ❌ Incorrect: sequential
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+
+// ✅ Correct: parallel where possible
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+
+  return Response.json({ data, config })
+}
+```
+
+### Promise.all() for Independent Operations
+
+**Impact**: CRITICAL - Reduces N round trips to 1
+
+```typescript
+// ❌ Incorrect: sequential (3 round trips)
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+
+// ✅ Correct: parallel (1 round trip)
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### Strategic Suspense Boundaries
+
+**Impact**: Faster initial paint
+
+Show wrapper UI immediately while data streams in:
+
+```tsx
+// ❌ Incorrect: all or nothing
+export default async function Page() {
+  const [header, content, sidebar] = await Promise.all([
+    fetchHeader(),
+    fetchContent(),
+    fetchSidebar()
+  ])
+  return <Layout header={header} content={content} sidebar={sidebar} />
+}
+
+// ✅ Correct: streams in progressively
+async function Header() {
+  const data = await fetchHeader()
+  return <header>{data}</header>
+}
+
+async function Content() {
+  const data = await fetchContent()
+  return <main>{data}</main>
+}
+
+async function Sidebar() {
+  const data = await fetchSidebar()
+  return <aside>{data}</aside>
+}
+
+export default function Page() {
+  return (
+    <>
+      <Suspense fallback={<HeaderSkeleton />}>
+        <Header />
+      </Suspense>
+      <Suspense fallback={<ContentSkeleton />}>
+        <Content />
+      </Suspense>
+      <Suspense fallback={<SidebarSkeleton />}>
+        <Sidebar />
+      </Suspense>
+    </>
+  )
+}
+```
+
+**Share promises with `use()` hook**:
+
+```tsx
+const dataPromise = fetchData()
+
+function ParentComponent() {
+  return (
+    <>
+      <ChildA dataPromise={dataPromise} />
+      <ChildB dataPromise={dataPromise} />
+    </>
+  )
+}
+
+function ChildA({ dataPromise }) {
+  const data = use(dataPromise)  // Shares same promise
+  return <div>{data.title}</div>
+}
+
+function ChildB({ dataPromise }) {
+  const data = use(dataPromise)  // Same promise, no duplicate fetch
+  return <div>{data.count}</div>
+}
+```
+
+## Server-Side Performance
+
+### Cross-Request LRU Caching
+
+**Impact**: HIGH - Especially with Vercel Fluid Compute
+
+`React.cache()` only works within one request. Use LRU cache for sequential user actions:
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const userCache = new LRUCache<string, User>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = userCache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  userCache.set(id, user)
+  return user
+}
+```
+
+**Why this matters**: With Vercel Fluid Compute, the same instance handles multiple requests from the same user. LRU cache survives across requests.
+
+### Minimize Serialization at RSC Boundaries
+
+**Impact**: HIGH - Reduces data transfer size
+
+Only pass fields the client actually uses:
+
+```typescript
+// ❌ Incorrect: serializes all 50 fields
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />  // Client uses 1 field
+}
+
+// ✅ Correct: serializes only 1 field
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+// ✅ Alternative: transform before passing
+async function Page() {
+  const user = await fetchUser()
+  const clientData = {
+    name: user.name,
+    avatar: user.avatar
+  }
+  return <Profile user={clientData} />
+}
+```
+
+**Why this matters**: Data is embedded in HTML response AND RSC requests. Large objects increase payload size and parsing time.
+
+### Parallel Data Fetching with Component Composition
+
+**Impact**: CRITICAL - Eliminates server-side waterfalls
+
+RSCs execute sequentially within a tree. Restructure to parallelize:
+
+```tsx
+// ❌ Incorrect: Sidebar waits for Page's fetch
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />  {/* Waits for header */}
+    </div>
+  )
+}
+
+// ✅ Correct: both fetch simultaneously
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />  {/* Parallel! */}
+    </div>
+  )
+}
+```
+
+**Pro tip**: Move async calls into separate components at the same level to maximize parallelism.
+
+### Per-Request Deduplication with React.cache()
+
+**Impact**: HIGH - Prevents duplicate queries in one render
+
+**Important**: In Next.js, `fetch` is auto-deduplicated. Use `React.cache()` for:
+- Database queries
+- Heavy computations
+- Auth checks
+- File system operations
+
+```typescript
+import { cache } from 'react'
+
+// ✅ Correct: multiple calls = one execution
+export const getUser = cache(async (id: string) => {
+  return await db.user.findUnique({ where: { id } })
+})
+
+// Usage in multiple components
+async function Profile() {
+  const user = await getUser('123')  // Executes
+  return <div>{user.name}</div>
+}
+
+async function Avatar() {
+  const user = await getUser('123')  // Cached!
+  return <img src={user.avatar} />
+}
+```
+
+**Warning**: Avoid inline objects as arguments (always cache miss):
+
+```typescript
+// ❌ Incorrect: cache miss every time (different object reference)
+const getData = cache(async (options: { id: string }) => {
+  return await db.query(options.id)
+})
+getData({ id: '123' })  // Miss
+getData({ id: '123' })  // Miss (different object!)
+
+// ✅ Correct: use primitives or stable references
+const getData = cache(async (id: string) => {
+  return await db.query(id)
+})
+getData('123')  // Hit
+getData('123')  // Hit
+```
+
+### Use after() for Non-Blocking Operations
+
+**Impact**: HIGH - Faster response times
+
+Schedule work after response is sent:
+
+```typescript
+import { after } from 'next/server'
+
+export async function POST(request: Request) {
+  const data = await request.json()
+  await updateDatabase(data)
+
+  after(async () => {
+    // These don't block the response
+    await logUserAction(data)
+    await sendAnalytics(data)
+    await invalidateCache(data.id)
+    await sendNotification(data.userId)
+  })
+
+  return new Response(JSON.stringify({ status: 'success' }))
+}
+```
+
+**Perfect for**:
+- Analytics
+- Audit logging
+- Notifications
+- Cache invalidation
+- External webhooks
+
+## Bundle Size Optimization
+
+### Avoid Barrel File Imports
+
+**Impact**: CRITICAL - 200-800ms import cost, 15-70% faster builds
+
+Popular libraries have 1000s of re-exports. Tree-shaking doesn't help:
+
+```typescript
+// ❌ Incorrect: loads 1,583 modules, ~2.8s in dev
+import { Check, X, Menu } from 'lucide-react'
+
+// ✅ Correct: loads only 3 modules
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+
+// ✅ Best: Next.js 13.5+ (auto-optimized)
+// next.config.js
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material', '@mui/icons-material']
+  }
+}
+// Then use barrel imports normally
+import { Check, X, Menu } from 'lucide-react'  // Optimized!
+```
+
+**Affected libraries**: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`
+
+### Conditional Module Loading
+
+**Impact**: HIGH - Reduces initial bundle
+
+Load large modules only when feature is activated:
+
+```typescript
+// ❌ Incorrect: always bundled
+import { processData } from './heavy-library'
+
+export default function Component() {
+  const [advanced, setAdvanced] = useState(false)
+
+  if (!advanced) return <SimpleView />
+
+  return <AdvancedView data={processData(input)} />
+}
+
+// ✅ Correct: loaded only when needed
+export default function Component() {
+  const [advanced, setAdvanced] = useState(false)
+
+  if (!advanced) return <SimpleView />
+
+  const { processData } = await import('./heavy-library')
+  return <AdvancedView data={processData(input)} />
+}
+```
+
+**Client-side SSR prevention**:
+
+```typescript
+// Prevents bundling in server bundle
+if (typeof window !== 'undefined') {
+  const { heavyClientLib } = await import('./client-only')
+}
+```
+
+### Defer Non-Critical Third-Party Libraries
+
+**Impact**: HIGH - Analytics/monitoring don't block interaction
+
+Load after hydration:
+
+```tsx
+// ❌ Incorrect: blocks hydration
+import Analytics from 'analytics-lib'
+
+export default function Layout({ children }) {
+  return (
+    <>
+      <Analytics />
+      {children}
+    </>
+  )
+}
+
+// ✅ Correct: loads after hydration
+const Analytics = dynamic(() => import('./Analytics'), {
+  ssr: false  // Client-only
+})
+
+export default function Layout({ children }) {
+  return (
+    <>
+      {children}
+      <Analytics />
+    </>
+  )
+}
+```
+
+### Dynamic Imports for Heavy Components
+
+**Impact**: CRITICAL - Directly affects TTI and LCP
+
+Example: Monaco Editor (~300KB) should always be dynamic:
+
+```tsx
+// ❌ Incorrect: adds 300KB to initial bundle
+import Editor from '@monaco-editor/react'
+
+export default function Page() {
+  return <Editor />
+}
+
+// ✅ Correct: loaded on demand
+const Editor = dynamic(() => import('@monaco-editor/react'), {
+  loading: () => <div>Loading editor...</div>,
+  ssr: false
+})
+
+export default function Page() {
+  return <Editor />
+}
+```
+
+### Preload Based on User Intent
+
+**Impact**: MEDIUM-HIGH - Feels instant
+
+Preload before click using hover/focus:
+
+```tsx
+import { useState } from 'react'
+
+function NavigationLink({ href, children }) {
+  const [isPreloading, setIsPreloading] = useState(false)
+
+  return (
+    <Link
+      href={href}
+      onMouseEnter={() => {
+        if (!isPreloading) {
+          setIsPreloading(true)
+          // Preload route
+          router.prefetch(href)
+        }
+      }}
+      onFocus={() => {
+        if (!isPreloading) {
+          setIsPreloading(true)
+          router.prefetch(href)
+        }
+      }}
+    >
+      {children}
+    </Link>
+  )
+}
+```
+
+## Data Fetching Strategies
+
+### fetch is Auto-Deduplicated
+
+**Built-in**: Same URL + options = one request per render
+
+```tsx
+// ✅ Automatic deduplication
+async function Header() {
+  const data = await fetch('/api/data')  // Request 1
+  return <div>{data.title}</div>
+}
+
+async function Content() {
+  const data = await fetch('/api/data')  // Deduplicated!
+  return <div>{data.body}</div>
+}
+```
+
+### React.cache() for Non-Fetch
+
+Use for DB queries, file ops, computations:
+
+```typescript
+import { cache } from 'react'
+
+export const getSettings = cache(async () => {
+  // Heavy computation or DB query
+  return await db.settings.findFirst()
+})
+```
+
+### Client-Side: Use SWR for Deduplication
+
+```typescript
+import useSWR from 'swr'
+
+// Multiple instances share one request
+function Component() {
+  const { data } = useSWR('/api/user', fetcher)
+  return <div>{data?.name}</div>
+}
+
+// Use useImmutableSWR for static data
+import { useImmutableSWR } from 'swr/immutable'
+
+function StaticComponent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+  return <div>{data?.appName}</div>
+}
+```
+
+## Server Actions Best Practices
+
+### Prevent Waterfalls
+
+```typescript
+'use server'
+
+// ❌ Incorrect: sequential
+export async function updateProfile(data: FormData) {
+  const user = await getUser()
+  const validated = await validateData(data)
+  const result = await saveToDb(validated)
+  return result
+}
+
+// ✅ Correct: parallel where possible
+export async function updateProfile(data: FormData) {
+  const userPromise = getUser()
+  const validatedPromise = validateData(data)
+
+  const [user, validated] = await Promise.all([
+    userPromise,
+    validatedPromise
+  ])
+
+  const result = await saveToDb(validated)
+  return result
+}
+```
+
+### Use after() for Non-Blocking Work
+
+```typescript
+'use server'
+
+import { after } from 'next/server'
+
+export async function createPost(data: FormData) {
+  const post = await db.post.create({ data })
+
+  after(async () => {
+    await revalidatePath('/blog')
+    await sendNotification(post.authorId)
+    await trackEvent('post_created', { postId: post.id })
+  })
+
+  return { success: true, postId: post.id }
+}
+```
+
+### React.cache() for Shared Logic
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session) return null
+  return await db.user.findUnique({ where: { id: session.userId } })
+})
+
+// Multiple server actions can call this
+export async function updateProfile(data: FormData) {
+  const user = await getCurrentUser()  // Cached
+  // ...
+}
+
+export async function deleteAccount() {
+  const user = await getCurrentUser()  // Same cache
+  // ...
+}
+```
+
+## Anti-Patterns to Avoid
+
+### Critical Anti-Patterns
+1. ❌ Sequential awaits for independent operations
+2. ❌ Barrel file imports (200-800ms overhead)
+3. ❌ Awaiting in parent RSC before rendering children
+4. ❌ Passing entire objects across RSC boundary
+
+### High-Impact Anti-Patterns
+5. ❌ No deduplication for repeated calls (use React.cache/SWR)
+6. ❌ Blocking responses with logging/analytics (use after())
+7. ❌ Inline objects as React.cache() arguments
+8. ❌ Not using optimizePackageImports for icon libraries
+
+### Subtle Bugs
+9. ❌ Forgetting `ssr: false` for client-only libraries
+10. ❌ Not hoisting async calls to enable parallelization
+11. ❌ Using barrel imports in dev (slow HMR)
+12. ❌ LRU cache without TTL (memory leak)
+
+## Key Metrics
+
+| Optimization | Improvement |
+|---|---|
+| Eliminate waterfalls | 2-10× faster |
+| Avoid barrel imports | 15-70% faster builds, 28% faster HMR |
+| Bundle size reduction | Direct TTI/LCP impact |
+| LRU caching | Eliminates redundant DB queries |
+| Parallel RSC composition | Eliminates server waterfalls |
+| after() for non-blocking | 50-200ms faster responses |
+
+**Reference**: [Vercel React Best Practices](https://github.com/vercel/react-best-practices)