76 lines (54 loc) · 2.3 KB

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