davenov:cc:expert-nextjs-16

<essential_principles>

Enable with:

// next.config.js
const nextConfig = { cacheComponents: true }

Then use 'use cache' directive to cache specific components/functions:

async function CachedData() {
  'use cache'
  const data = await db.query(...)
  return <div>{data}</div>
}

Control cache lifetime with cacheLife() and tag for revalidation with cacheTag(). </principle>

Migration: Rename middleware.ts → proxy.ts, rename export to proxy.

Proxy is ONLY for:

• •Rewrites
• •Redirects
• •Headers
• •High-level traffic control (e.g., redirect users without session cookie)

Proxy is NOT for:

• •Authentication logic (use Data Access Layer)
• •Database calls
• •Complex business logic
• •Session management

Use Server Layout Guards or Data Access Layer (DAL) for auth checks. </principle>

Pattern: Fetch data in Server Components, pass to Client Components as props.

// Server Component (default)
export default async function Page() {
  const data = await getData()
  return <ClientButton data={data} />
}

// Client Component
'use client'
export function ClientButton({ data }) {
  return <button onClick={() => handleClick(data)}>Click</button>
}

Push 'use client' boundary as low as possible in component tree. </principle>

// lib/dal.ts
export async function getUser() {
  const session = await verifySession()
  if (!session) redirect('/login')
  return session.user
}

// Any page/component
export default async function Dashboard() {
  const user = await getUser() // Auth check happens here
  return <div>Welcome {user.name}</div>
}

This ensures auth is verified at every data access point, not just at route level. </principle>

No configuration needed. Webpack is still available via --webpack flag if needed. </principle>

</essential_principles>

<quick_start> What would you like to do?

1. •Build a new Next.js 16 app
2. •Debug an existing app
3. •Add a feature
4. •Write/run tests
5. •Optimize performance
6. •Ship/deploy
7. •Migrate from Next.js 15
8. •Something else

Wait for response before proceeding. </quick_start>

After reading the workflow, follow it exactly. </routing>

<verification_loop> After every change:

# 1. Does it build?
npm run build

# 2. Do types pass?
npx tsc --noEmit

# 3. Does it run?
npm run dev
# Then check http://localhost:3000

# 4. Do tests pass? (if applicable)
npm test

Report to user:

• •"Build: OK" or "Build: X errors"
• •"Types: OK" or "Types: X errors"
• •"Dev server: Running at localhost:3000" </verification_loop>

<reference_index>

Architecture:

• •architecture.md - Project structure, App Router patterns, route groups
• •server-client-components.md - When to use Server vs Client Components

Core Features:

• •cache-components.md - use cache, cacheLife, cacheTag, revalidation
• •proxy.md - proxy.ts patterns, migration from middleware
• •server-actions.md - Form handling, mutations, optimistic updates
• •data-fetching.md - Fetching patterns, streaming, Suspense

Authentication & Security:

• •authentication.md - Auth patterns, DAL, Server Layout Guards
• •security.md - CSP, CORS, CVE mitigations, Server Action security

Performance:

• •performance.md - React Compiler, bundle optimization, Turbopack
• •image-optimization.md - next/image, formats, sizing
• •font-optimization.md - next/font, preloading, subsetting

Development:

• •devtools-mcp.md - AI-assisted debugging, MCP integration
• •testing.md - Unit tests, integration tests, E2E with Playwright

Deployment:

• •deployment-vercel.md - Zero-config Vercel deployment
• •deployment-docker.md - Docker containerization, multi-stage builds
• •deployment-self-hosted.md - Node.js server, standalone output

Migration:

• •migration-from-15.md - Breaking changes, codemods, upgrade path

</reference_index>

<workflows_index>

<success_criteria> A well-built Next.js 16 app:

• •Uses cacheComponents: true with explicit use cache directives
• •Uses proxy.ts only for routing (NOT auth)
• •Has clear Server/Client Component boundaries
• •Uses Data Access Layer for authentication
• •Builds without errors
• •Has TypeScript strict mode enabled
• •Passes all tests
• •Scores well on Core Web Vitals </success_criteria>