Next.js 16.1+

Async params

Type params and searchParams as Promise<>, await in component body.

→ examples/async-params.tsx

Caching Overview

Enable cacheComponents: true in next.config.ts.

| Directive | Runtime APIs | Storage | Use Case | |-----------|-------------|---------|----------| | "use cache" | No | In-memory | Static shared content | | "use cache: private" | Yes | Browser only | User-specific data | | "use cache: remote" | No | Remote cache | Multi-instance shared |

"use cache"

Cache routes, components, or functions. Data fetching cached as part of static shell.

Serialization Rules

Supported: primitives, plain objects, arrays, Date, Map, Set, React elements (pass-through only)

Unsupported: class instances, functions (except pass-through), Symbols, WeakMap/WeakSet

Pass-Through Pattern

Accept non-serializable values (children, actions) without introspecting them.

Runtime API Constraint

Cannot access cookies(), headers(), searchParams inside cached scope. Read outside and pass as args.

→ examples/use-cache.tsx

"use cache: private"

Allows runtime APIs inside cache. Results cached in browser memory only, never on server.

Constraints:

• Executes on every server render
• Excluded from static shell
• cacheLife stale time must be ≥30s

→ examples/use-cache-private.tsx

"use cache: remote"

Stores output in remote cache. Durable across instances/deployments.

Use when:

• Rate-limited APIs
• Slow/expensive backends
• Serverless (ephemeral memory)

Avoid when:

• Fast operations (<50ms)
• High-cardinality cache keys
• Frequently changing data

→ examples/use-cache-remote.tsx

"use client"

Marks client-side entry point. Add at top of file before imports.

'use client'

import { useState } from 'react'

export default function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
}

Props must be serializable. Functions cannot be passed from server to client.

"use server"

Marks Server Actions. Can be file-level or inline.

// File-level
'use server'
export async function createUser(formData: FormData) {
  await db.user.create({ data: Object.fromEntries(formData) })
  revalidatePath('/users')
}

// Inline
async function submitForm(formData: FormData) {
  'use server'
  await saveData(formData)
}

Invalidation

import { cacheTag, revalidateTag, updateTag } from 'next/cache'

// Tag cached data
async function getData() {
  'use cache'
  cacheTag('products')
  return fetch('/api/products')
}

// Invalidate
revalidateTag('products', 'hours')  // SWR-style with profile
updateTag('products')               // Server Actions: immediate

Profiles: 'hours' (1h), 'days' (1d), 'weeks' (1w), 'max' (1y)

Cache Lifetime

import { cacheLife } from 'next/cache'

async function getData() {
  'use cache'
  cacheLife('hours')  // Profile shorthand
  // or
  cacheLife({ stale: 300, revalidate: 900, expire: 3600 })
}

Proxy (auth/routing)

Use proxy.ts instead of middleware.ts. Runs on Node.js runtime.

→ examples/proxy.ts

Common Mistakes

| ❌ Wrong | ✅ Correct | |----------|-----------| | 'use cache' with cookies() inside | Read cookies outside, pass as arg | | Creating JSX inside cache, passing to client | Pass data to client, render there | | middleware.ts | proxy.ts | | revalidateTag(tag) | revalidateTag(tag, 'hours') | | Cache high-cardinality keys | Cache low-cardinality, filter in-memory |