Next.js Best Practices

Use this skill when

Use for Next.js App Router work: pages/layouts/loading/error files, React Server Component boundaries, route handlers, async params/searchParams/cookies/headers, metadata, images/fonts, Suspense, bundling, or hydration/build errors.

Workflow

1. Identify which Next.js surface is changing: route tree, component boundary, API route, runtime, asset/metadata, or build config.
2. Read only the matching reference file(s) below; avoid loading unrelated topics.
3. Keep pages thin and prefer this repo's API/OpenAPI and lib helper boundaries.
4. Run the relevant Next.js checks (bun run lint, bun run typecheck, bun run build) or record the local toolchain blocker.

Skill graph

Read references/graph.md for routing. Related skills: setup-product, add-api-endpoint, better-auth-best-practices, vercel-deployment, testing-infra, next-cache-components, next-upgrade.

References

• references/workflow.md: how to choose the right Next.js reference.
• references/file-conventions.md: route tree and special files.
• references/rsc-boundaries.md: Server/Client Component rules.
• references/async-patterns.md: Next.js 15+ async APIs.
• references/data-patterns.md: fetching, mutations, waterfalls.
• references/route-handlers.md: API route handlers.
• references/runtime-selection.md: Node.js vs Edge runtime.
• references/directives.md: use client, use server, use cache.
• references/functions.md: navigation/server/generate functions.
• references/error-handling.md: errors, redirects, not found, auth errors.
• references/metadata.md: metadata and OG image conventions.
• references/image.md: image optimization.
• references/font.md: font optimization.
• references/bundling.md: package/CSS/polyfill compatibility.
• references/scripts.md: third-party scripts.
• references/hydration-error.md: hydration mismatch debugging.
• references/suspense-boundaries.md: CSR bailout and Suspense rules.
• references/parallel-routes.md: modal and slot patterns.
• references/self-hosting.md: standalone/self-hosting notes.
• references/debug-tricks.md: Next.js debugging tricks.

Scripts

See scripts/README.md. Run the inspector before broad Next.js refactors.

Assets

See assets/README.md for checklists and evals.