Expert Next.js Developer Companion

Builds production-grade Next.js 16 applications using App Router, Server Components, Turbopack, and modern caching strategies.

When to Use This Agent

Choose this agent when you need to:

• Scaffold or extend Next.js 16 apps with Server Components, layouts, and route handlers
• Implement use cache directive, Partial Pre-Rendering, and advanced revalidation APIs
• Configure Turbopack builds, metadata, middleware auth, and deployment pipelines

Consider alternatives when:

• Your project uses the legacy Pages Router without migration plans
• You need framework-agnostic React guidance without Next.js-specific patterns

Quick Start

Configuration

Copy
name: expert-nextjs-developer-companion
type: agent
category: web-tools

Example Invocation

Copy
claude agent:invoke expert-nextjs-developer-companion "Create a dynamic product page with ISR and async params"

Example Output

Created: app/products/[slug]/page.tsx
  - Async params (Next.js 16 breaking change)
  - generateMetadata with OG tags
  - ISR with revalidate: 3600
  - Suspense boundary for streaming
Created: app/products/[slug]/loading.tsx
Created: app/actions/update-product.ts
  - Server Action with revalidateTag

Core Concepts

Next.js 16 Feature Matrix

Aspect	Details
App Router	File-based routing with layouts, templates, route groups, and parallel routes
Cache Components	use cache directive for Partial Pre-Rendering and instant navigation
Turbopack	Default bundler with filesystem caching for sub-second HMR
Async Params	Breaking change: params and searchParams are Promise types requiring await
Cache APIs	updateTag(), refresh(), and enhanced revalidateTag() for granular invalidation

Request Lifecycle

+------------------+     +------------------+     +-------------------+
|  Incoming        |---->|  Middleware       |---->|  Route            |
|  Request         |     |  (auth/redirect)  |     |  Resolution       |
+------------------+     +------------------+     +-------------------+
                                                          |
         +-------------------+     +-------------------+  |
         |  Response         |<----|  Server Component  |<-+
         |  Streaming        |     |  + Cache Layer     |
         +-------------------+     +-------------------+

Configuration

Parameter	Type	Default	Description
next_version	string	"16"	Next.js version for feature-specific patterns
typescript_strict	boolean	true	Strict TypeScript with async param types
caching_strategy	string	"hybrid"	Approach: "static", "dynamic", "hybrid", or "ppr"
turbopack_fs_cache	boolean	true	Enable Turbopack filesystem cache
deployment_target	string	"vercel"	Platform: "vercel", "docker", "node", or "edge"

Best Practices

1. Always Await Params - Next.js 16 changed params and searchParams to Promise types. Every component destructuring these props must await them first. Missing await causes silent undefined values and blank pages.

2. Default to Server Components - Start every component as a Server Component. Add 'use client' only for useState, useEffect, event handlers, or browser APIs. This minimizes bundle sizes and avoids client-server waterfalls.

3. Leverage use cache for PPR - Mark data-fetching components with "use cache" to serve a static shell instantly while streaming dynamic content. This improves TTFB without sacrificing freshness.

4. Colocate Route Files - Place loading.tsx, error.tsx, and components alongside page.tsx in the same directory. This makes route-state relationships explicit and prevents orphaned files.

5. Use Granular Cache Tags - Apply entity-specific tags like product-${id} alongside collection tags. This enables surgical revalidation without flushing the entire cache.

Common Issues

1. Stale Data After Mutations - Server Actions that forget revalidateTag or revalidatePath leave cached pages serving outdated content. Always pair mutations with explicit cache invalidation.

2. Client Boundary Creep - Adding 'use client' to a parent forces all children to become client components. Push the boundary deep by extracting interactive elements into small leaf components.

3. Heavy Middleware - Middleware runs on every matching request. Keep it to lightweight checks (cookie validation, redirects) and defer expensive operations to route handlers.