Next.js Optimization Recipes

Next.js App Router changed the mental model for React applications. Server Components, streaming, parallel routes, intercepting routes — the surface area is huge and AI tools sometimes generate Pages Router patterns by mistake. These recipes produce App Router code exclusively, with correct server/client boundaries and proper data patterns.

What You Will Walk Away With

• Server Component and Server Action recipes with correct boundaries
• Data fetching patterns using RSC, streaming, and Suspense
• Authentication and middleware recipes for App Router
• Performance optimization prompts for Core Web Vitals

---

Recipe 1: Streaming with Independent Suspense Boundaries

Scenario: Your dashboard page makes 4 independent API calls. They all block rendering until the slowest one resolves.

Tip

Refactor app/dashboard/page.tsx to use streaming with Suspense boundaries. The page is a Server Component (no “use client”). It makes 4 independent data fetches: getStats(), getRecentOrders(), getTopProducts(), getActivityFeed(). Wrap each data-dependent section in its own <Suspense fallback={<SectionSkeleton />}> boundary. Create an async component for each section that fetches its own data: StatsSection, RecentOrdersSection, TopProductsSection, ActivityFeedSection. The page shell renders immediately. Each section streams in as its data resolves. Do NOT use Promise.all — each section is independent. Create matching skeleton components that match final layout dimensions to prevent layout shift. Add proper metadata using the generateMetadata export.

Expected output: Page with 4 Suspense boundaries, 4 async section components, 4 skeletons, and metadata.

---

Recipe 2: Server Actions for Form Handling

Scenario: You need a contact form that validates server-side, handles errors, and shows pending state without a separate API route.

Tip

Create a contact form with Server Actions. (1) app/contact/actions.ts with “use server”: submitContactForm action accepting FormData, validating with Zod (name required, email valid, message 10-1000 chars, honeypot empty), saving to database, sending email via Resend, returning success or field-level errors. (2) app/contact/page.tsx as Server Component containing the form. (3) app/contact/contact-form.tsx as Client Component using useActionState for the action and field errors, useFormStatus for submit button state, progressive enhancement so the form works without JavaScript. (4) After success, show message and reset form. (5) Rate limit: 5 submissions per hour per IP using KV store. Test with valid data, validation errors, and rate limit exceeded.

Expected output: Server action, page component, client form component, and tests.

---

Recipe 3: Authentication with NextAuth.js v5

Scenario: You need email/password and OAuth authentication with session management and protected routes.

A NextAuth scaffold spans auth.ts, middleware.ts, the [...nextauth] route handler, the client wrapper, and components — the server/client boundary is where AI tools slip up most, so pick the workflow that lets you police it.

Cursor

Use agent mode to scaffold auth.ts, middleware.ts, and the route handler together, then checkpoint before accepting. Auth is the classic case where the AI sprinkles "use client" onto a Server Component and silently kills SSR — the inline diff lets you catch the wrong directive before it ships.

Claude Code

Generate the whole auth surface in one headless pass, then guard the boundary with a hook: add a PostToolUse hook on *.tsx that greps for "use client" co-located with a generateMetadata or auth() server call and fails the edit. Run claude -p "set up NextAuth v5 per auth.ts and protect /dashboard via middleware" so the middleware matcher and callbacks land in a single turn.

Codex

Develop auth in a worktree so the half-finished middleware.ts never breaks your running dev branch, then push and let the Cloud reviewer check the protected-route matcher and JWT callback exposure before merge — session/role leaks are exactly what a fresh review pass catches.

Tip

Set up NextAuth.js v5 with App Router. (1) Create auth.ts with NextAuth() configuration: Credentials provider (email/password with bcrypt), Google, GitHub. Drizzle adapter for DB sessions. JWT with 30-day maxAge. Callbacks: jwt includes userId and role, session exposes them. (2) middleware.ts protecting /dashboard/, /admin/, /api/* except /api/auth/*. (3) Route handler at app/api/auth/[...nextauth]/route.ts. (4) Typed useSession wrapper in lib/auth-client.ts. (5) LoginForm Client Component with email/password and OAuth buttons. (6) UserMenu with avatar, name, sign-out. (7) withAuth(Component, { role? }) HOC for server-side auth checking. Test login flow, session persistence, protected redirects, and role-based access.

Expected output: Auth config, middleware, route handler, client utilities, components, HOC, and tests.

---

Recipe 4: Parallel and Intercepting Routes for Modals

Scenario: Product details should open in a modal from the list but show a full page when accessed directly.

Tip

Implement intercepting routes for a product modal. (1) app/products/page.tsx — Server Component listing products in a grid linking to /products/[id]. (2) app/products/[id]/page.tsx — full detail page for direct access. (3) app/products/@modal/(.)products/[id]/page.tsx — intercepting route rendering the same data inside a modal. (4) app/products/layout.tsx rendering children and modal as parallel slots. (5) ProductModal.tsx Client Component with backdrop click to close (router.back()), Escape key, focus trapping, and “View full page” link. (6) Handle navigation correctly: router.back() returns to list, browser back closes modal, refresh shows full page. Test all navigation scenarios.

Expected output: Product pages, intercepting route, layout with parallel slots, modal component, and tests.

---

Recipe 5: Edge API Route Handlers

Scenario: You need low-latency API routes running on the edge with typing, validation, and caching.

Tip

Create API route handlers in app/api/products/. (1) route.ts with GET (list with pagination, filtering, sorting) and POST (create with Zod validation). (2) [id]/route.ts with GET, PUT, DELETE (soft-delete). (3) Add export const runtime = 'edge'. (4) Create lib/api-utils.ts with helpers: validateBody<T>(schema, request), paginatedResponse(data, total, page, pageSize), apiError(status, message, details?). (5) Add auth checking via auth() from NextAuth. (6) GET requests return Cache-Control with stale-while-revalidate. POST/PUT/DELETE purge cache tags with revalidateTag(). (7) Add JSDoc @swagger comments. Test each endpoint with valid requests, validation errors, auth failures, and not-found.

Expected output: Route handlers, API utility library, and tests for each endpoint.

---

Recipe 6: Incremental Static Regeneration for Blog

Scenario: Your blog has 500 posts. Full static generation takes 10 minutes. You need ISR.

Tip

Implement ISR. (1) In app/blog/page.tsx, fetch with { next: { revalidate: 3600 } } for 1-hour cache. (2) In app/blog/[slug]/page.tsx, use generateStaticParams() for the 50 most recent posts. Set dynamicParams = true and revalidate = 86400. (3) Create app/api/revalidate/route.ts webhook handler calling revalidatePath and revalidateTag when CMS publishes. (4) Add fetch tags: { next: { tags: ['post-' + slug, 'blog-posts'] } }. (5) Generate sitemap at app/sitemap.ts using MetadataRoute.Sitemap. (6) Add opengraph-image.tsx for dynamic OG images using ImageResponse from next/og. Test that revalidation webhook triggers cache purge.

Expected output: Blog pages with ISR, revalidation webhook, sitemap, OG image generation, and tests.

---

Recipe 7: Edge Middleware for A/B Testing and Feature Flags

Scenario: Split traffic between landing page variants and gate features behind flags at the edge.

Tip

Create middleware.ts for A/B testing and feature flags. (1) A/B: check for ab-variant cookie, assign randomly if missing, set for 30 days. Rewrite /pricing to /pricing/variant-a or variant-b invisibly. (2) Feature flags: fetch from KV keyed by user/anonymous ID, set as x-feature-flags request header for Server Components. (3) Geolocation: read request.geo, redirect / to /en or /es respecting language cookie. (4) Bot detection: check User-Agent, set x-is-bot header for skipping expensive personalizations. (5) Create composable middleware functions in lib/middleware-utils.ts. (6) Add config.matcher to skip static assets. Test each behavior with mocked NextRequest.

Expected output: Middleware, utility functions, variant directories, and tests.

---

Recipe 8: Dynamic Metadata and Structured Data System

Scenario: Every page needs unique meta tags, dynamic OG images, and JSON-LD structured data.

Tip

Create a metadata system. (1) In app/layout.tsx, set default metadata: title, description, OG image, Twitter card, robots. (2) Create lib/metadata.ts with generatePageMetadata(options) returning Metadata with template title, description, canonical URL, OG image, alternates, and JSON-LD. (3) For blog: generateMetadata fetching post, returning title, excerpt description, dynamic OG image from opengraph-image.tsx (Satori-rendered), article structured data. (4) For products: Product structured data with price, availability, rating. (5) Create app/robots.ts and app/sitemap.ts. (6) Verify no duplicate tags, proper canonicals, valid JSON-LD.

Expected output: Metadata utility, OG image generation, JSON-LD helpers, robots.ts, sitemap.ts, and tests.

---

Recipe 9: Core Web Vitals Optimization

Scenario: Lighthouse performance score is 65. LCP 4.2s, CLS 0.25, INP 320ms.

Vitals work splits cleanly into two halves: scattered component edits (images, fonts, dynamic imports) and a CI budget gate. Different tools own each half better.

Cursor

Use agent mode to sweep the component edits — next/image conversions, next/font swaps, useDeferredValue on the filter — across many files at once, watching the inline diffs so a priority prop does not land on every image. Cursor’s visual review is fastest for this kind of broad, repetitive change.

Claude Code

Best fit for the CI half: have it write the Lighthouse CI GitHub Action with hard budgets (LCP < 2.5s, CLS < 0.1, INP < 200ms) and wire web-vitals reporting headless. The terminal flow makes it trivial to run the Lighthouse pass locally and feed the failing audit JSON straight back into the next prompt.

Codex

Run the optimization as a Cloud task that opens a PR, so the before/after Lighthouse numbers and the new CI workflow get reviewed together. A worktree keeps the perf branch separate while the budgets settle.

Tip

Fix Core Web Vitals. (1) LCP: Convert hero images to next/image with priority, explicit dimensions, sizes attribute. Preload LCP image in metadata. (2) CLS: Add explicit dimensions to all images/embeds. Use Suspense skeletons matching final dimensions. Fix fonts with next/font display:swap and preload. (3) INP: Move filtering/sorting to useDeferredValue or useTransition. Split large Client Components with dynamic imports and ssr:false. (4) General: Enable PPR if available. Use Script strategy=“lazyOnload” for analytics. Configure images: { formats: ['image/avif', 'image/webp'] }. (5) Set up web-vitals reporting. Add Lighthouse CI in GitHub Actions with budgets: LCP < 2.5s, CLS < 0.1, INP < 200ms.

Expected output: Optimized components, config changes, font setup, Lighthouse CI workflow, and metrics.

---

Recipe 10: Multi-Tenant SaaS Architecture

Scenario: Your SaaS serves multiple tenants from a single deployment with subdomain-based routing and data isolation.

Tip

Implement multi-tenancy. (1) In middleware.ts, extract tenant from subdomain, validate in KV, set as x-tenant-id header. (2) Create lib/tenant.ts with getTenant() reading the header in Server Components. (3) Create TenantProvider Client Component providing tenant context (name, theme, logo, features). (4) In database layer, every query includes WHERE tenant_id. Create scopedQuery(tenantId) wrapper for Drizzle. (5) Tenant-specific theming via CSS variables set in root layout. (6) Handle missing tenant subdomain with branded 404. Handle www and naked domain as marketing site. Test tenant isolation: queries never return other tenants’ data.

Expected output: Middleware, tenant utility, provider, scoped queries, themed layout, and isolation tests.

---

Recipe 11: Plugin Architecture for Extensible Dashboards

Scenario: Your dashboard needs user-installed plugins that add pages, API routes, and UI components.

Tip

Build a plugin system. (1) Define Plugin interface: id, name, version, routes, apiRoutes, sidebarItems, settingsComponent. (2) Create PluginRegistry loading plugins from database. (3) Catch-all route app/plugins/[pluginId]/[...path]/page.tsx dynamically loading plugin components. (4) API catch-all app/api/plugins/[pluginId]/[...path]/route.ts delegating to plugin handlers. (5) Sidebar reads active plugins and injects items. (6) Installation flow: upload bundle, validate manifest, store, register. (7) Sandbox: error boundary per plugin, scoped API access. Test loading, delegation, and isolation.

Expected output: Plugin interface, registry, catch-all routes, sidebar integration, installation flow, and tests.

---

Recipe 12: End-to-End Type Safety with tRPC

Scenario: Your 20 API endpoints have types that are always out of sync with the frontend.

tRPC’s payoff is end-to-end type inference, so the real test of any tool here is whether a change to a router output surfaces as a compile error on the client — not whether the files were generated.

Cursor

Scaffold server/trpc.ts, the routers, and the client wiring in agent mode, then prove the loop interactively: change a procedure’s return type and watch the red squiggle appear in the consuming component. The live type-checking in the editor is the fastest way to confirm inference is actually wired through.

Claude Code

Generate the full tRPC setup headless, then encode the contract as a check: add a PostToolUse hook running tsc --noEmit so any drift between a router and its useQuery call fails immediately. Ask it to add a deliberately-breaking test (claude -p "change posts.list output and confirm the component fails to typecheck") to lock the guarantee in.

Codex

Use a worktree to build the router layer in isolation, then push and let the Cloud reviewer confirm every procedure has Zod input validation and the isAuthed/isAdmin middleware is applied where it should be — the cross-cutting auth checks are easy to miss in a 20-endpoint diff.

Tip

Set up tRPC v11 with App Router. (1) server/trpc.ts with context (session, database), router, middleware (isAuthed, isAdmin). (2) server/routers/ with users, posts (cursor pagination), comments sub-routers. Each procedure has Zod input validation. (3) app/api/trpc/[trpc]/route.ts handler. (4) lib/trpc-client.ts with typed client. (5) lib/trpc-react.ts with @trpc/react-query integration. (6) In components, use trpc.posts.list.useQuery and trpc.posts.create.useMutation — fully typed from router with zero manual type definitions on client. (7) Add subscriptions for real-time. Test: changing router output type causes TypeScript errors in components.

Expected output: tRPC setup, routers, handler, typed client, React Query integration, and type-safety verification.

---

When Recipes Break

Caution

Common Next.js App Router pitfalls:

• “use client” placement: If the AI puts “use client” on the page component, the entire page loses SSR benefits. Only leaf interactive components should be client components.
• fetch deduplication: Next.js deduplicates identical Server Component fetches. Different query params mean separate requests.
• Server Action serialization: Actions can only accept/return serializable data. Dates and functions will fail at runtime.
• Metadata in Client Components: metadata and generateMetadata exports only work in Server Components. They are silently ignored in Client Components.

What Is Next

• React patterns for component-level recipes inside Next.js
• API patterns for standalone API design
• Docker patterns for containerizing your Next.js app