Next.js

Mandate

When working in a Next.js codebase, enforce App Router idioms (RSC by default), Suspense + error boundary co-location, next/image for all raster, Server Actions for mutations, and pinned framework version.

Decisions encoded

• App Router default. Pages Router only if the project is already there and a migration is out of scope.
• Server Components by default. Add "use client" ONLY at leaf interactivity (form, hook, event handler).
• Server Actions for mutations. No client-side fetch to /api/route for form posts; use action functions + revalidatePath/revalidateTag.
• next/image always. Raw <img> is an anti-pattern (no LCP optimization, no AVIF/WebP).
• Suspense boundaries co-located. Every route segment ships loading.tsx + error.tsx next to page.tsx.
• Middleware sparingly. Only for auth gating, header injection, redirects. NOT for data transforms (use route handlers).
• Pinned Next version. No "latest" in package.json; bump deliberately via /upgrade nextjs --to <ver>.

Project structure (App Router)

src/app/
├── layout.tsx              # root layout (must export metadata, fonts)
├── page.tsx                # /
├── loading.tsx + error.tsx # global Suspense + error boundaries
├── (marketing)/            # route group (no URL segment)
│   ├── about/page.tsx
│   └── pricing/page.tsx
├── (app)/                  # authed
│   ├── dashboard/
│   │   ├── page.tsx
│   │   ├── loading.tsx
│   │   ├── error.tsx
│   │   └── actions.ts      # Server Actions
│   └── settings/page.tsx
├── api/
│   └── webhooks/route.ts   # route handlers (NOT for app-internal data)
└── middleware.ts           # auth/redirect gating only

Procedure (new feature)

1. Determine route segment + group ((marketing), (app), etc.)
2. Create page.tsx (RSC by default) — fetch data with async/await, no useEffect
3. Co-locate loading.tsx + error.tsx
4. If interactivity needed → split into Client Component leaf, mark "use client"
5. Mutations → Server Action in actions.ts, return revalidation tag
6. Images → next/image with explicit width/height; priority for above-fold
7. Test: Playwright covers user journey; Vitest covers Server Action logic

Hard rules

• Use next/image for raster; never <img>
• Use next/font for fonts; never link to Google Fonts CDN (privacy + perf)
• Use Server Actions for mutations; not fetch('/api/...') from forms
• Match React 19's use() hook for promise unwrapping in Client Components
• Run next build locally before merging — production-only optimizations catch issues next dev doesn't
• Pin next exact version in package.json; bumps require /upgrade nextjs

Common pitfalls

1. Adding "use client" to the root layout — kills the whole RSC tree. Apply at leaves only.
2. useEffect in RSC — won't even compile. Symptom: "useEffect is not defined in server components."
3. Mutating in route handlers when Server Action would do — splits the surface area; Server Actions also auto-revalidate.
4. <img> slipping through — set ESLint rule @next/next/no-img-element to error.
5. Forgetting revalidatePath/revalidateTag after mutation — UI stays stale.
6. Edge runtime for data-heavy work — Edge has no Node APIs; use runtime: 'nodejs' for DB queries.

References

• Official docs: https://nextjs.org/docs/app
• App Router migration: https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration
• Server Actions: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations

Done means

• All new routes use App Router unless explicitly migrating from Pages
• next/image everywhere; no <img>
• Suspense + error boundaries co-located with every page
• next build passes locally before push