Next.js

Next.js App Router Best Practices

Overview

Enforces high-performance architectural patterns for Next.js App Router based on Vercel Engineering guidelines: React Server Components (RSC), zero-waterfall async pipelines, request deduplication via React.cache(), bundle optimization, and secure Server Actions.

When to Use

Activate whenever building, refactoring, or reviewing Next.js pages, layouts, Route Handlers (app/api), Server Actions, or components in the app/ directory.

Negative Constraints (What NOT to Do)

1. NEVER use barrel imports for UI libraries: Avoid import { Button, Dialog } from '@/components'. Import directly from the exact file (import { Button } from '@/components/ui/button') to prevent bundler tree-shaking failures and trace bloat.
2. NEVER trust client-provided data or session state in Server Actions: Always authenticate session and authorize tenant ownership inside the Server Action handler itself before mutating data.
3. NEVER introduce sequential await waterfalls for independent data: Always use Promise.all() or parallel streaming <Suspense> boundaries.
4. NEVER pass large unneeded serialized data from Server to Client Components: Only pass the specific primitive fields required by the client component (server-dedup-props).
5. NEVER use useEffect for data fetching: Fetch directly in Server Components or use TanStack Query / SWR for client-side queries.
6. NEVER import server-only modules in client components: Use the server-only package in data access layers to catch accidental client imports at build time.

Rules & Patterns

1. Eliminating Async Waterfalls (Critical)

• Parallel Fetching: Fetch independent data concurrently at the top of the route or component.
• Granular Streaming: Wrap slow, non-critical subtrees in <Suspense fallback={<Skeleton />}> so critical above-the-fold content streams immediately.
• Defer Awaits: Check cheap synchronous conditions before awaiting remote resources.