next-best-practices

name	next-best-practices
description	Next.js best practices - RSC boundaries, data patterns, async APIs, error handling, route handlers, directives, runtime selection
user-invocable	false

Next.js Best Practices

Apply these rules when writing or reviewing Next.js code.

Districtr Conventions

• Use React.FC<Props> syntax for reusable component declarations (pages/layouts use export default function as required by Next.js)
• Runtime is Bun (not Node.js); deployed on Fly.io with output: 'standalone'
• Map pages (/map/*) are almost entirely client-side — heavy 'use client' usage is expected
• Static content pages (tags, about, etc.) should be statically rendered at build time where possible

RSC Boundaries

Detect invalid React Server Component patterns.

See rsc-boundaries.md for:

• Async client component detection (invalid)
• Non-serializable props detection
• Server Action exceptions

Async Patterns

Next.js 15+ async API changes.

See async-patterns.md for:

• Async params and searchParams
• Async cookies() and headers()
• Migration codemod

Runtime Selection

See runtime-selection.md for:

• Default to Node.js runtime
• When Edge runtime is appropriate

Directives

See directives.md for:

• 'use client', 'use server' (React)
• 'use cache' (Next.js)

Functions

See functions.md for:

• Navigation hooks: useRouter, usePathname, useSearchParams, useParams
• Server functions: cookies, headers, draftMode, after
• Generate functions: generateStaticParams, generateMetadata

Error Handling

See error-handling.md for:

• error.tsx, global-error.tsx, not-found.tsx
• redirect, permanentRedirect, notFound
• forbidden, unauthorized (auth errors)
• unstable_rethrow for catch blocks

Data Patterns

See data-patterns.md for:

• Server Components vs Server Actions vs Route Handlers
• Avoiding data waterfalls (Promise.all, Suspense, preload)
• Client component data fetching

Route Handlers

See route-handlers.md for:

• route.ts basics
• GET handler conflicts with page.tsx
• Environment behavior (no React DOM)
• When to use vs Server Actions