nextjs-patterns

nextjs-patterns

Compatibility

• Tested against: Next.js 14.x and 15.x (App Router), React 18+ / 19+.
• Pages Router is out of scope. On a Pages-Router project (no app/), fall back to plain React skills; ask before introducing App Router.

When to use

Use this skill for Next.js-specific code generation and editing on the App Router:

• Server Components (RSC) and Client Components ("use client")
• Server Actions ("use server")
• Route Handlers (app/api/**/route.ts)
• Layouts, templates, loading / error / not-found boundaries
• Data fetching with fetch + cache directives
• revalidatePath / revalidateTag invalidation
• Streaming and <Suspense> boundaries
• Middleware (middleware.ts)
• Metadata API (static + dynamic)
• Route Groups, Parallel Routes, Intercepting Routes

When to use the analysis sibling

When the task is understanding how a Next.js app boots, where the server/client boundary lives, what is cached vs streamed, or why a hydration mismatch fires — defer to project-analysis-nextjs first, then return here for the edit.

Procedure: write Next.js code

1. Confirm App Router — app/ directory exists; next.config.{js,ts,mjs} present.
2. Confirm version — package.json major for next. 14.x vs 15.x differs in default caching (15.x is uncached by default for fetch) and in cookies() / headers() being async.
3. Inspect routing layout — flat app/ vs grouped (app/(marketing)/, app/(app)/); identify shared layouts and parallel routes.
4. Inspect data layer — Server Actions vs route handlers vs external API; ORM (Prisma, Drizzle) or fetch-based.
5. Inspect styling — Tailwind, CSS Modules, or styled engine; respect the chosen stack, do not mix.
6. Check test conventions — Vitest / Jest + RTL for components; Playwright for E2E; route-handler tests via node runtime.

Server vs Client boundary

• Server Components are the default. Add "use client" only when a leaf component needs state, effects, browser APIs, or event handlers.
• The "use client" boundary is viral upward at the import graph, but you can keep a Server Component rendered as a child of a Client Component by passing it as a prop / children — that pattern keeps server logic out of the client bundle.
• Never put database access, secrets, or server-only modules inside a Client Component or a file imported by one. Use import "server-only" at the top of a server module to make leaks fail at build time.
• Symmetric guard: import "client-only" for code that must never run on the server (e.g. browser-only SDKs).
• Props passed from Server → Client must be serializable. No functions, no Dates with custom prototypes, no Map / Set — use plain JSON.