Next.js Best Practices

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

File Conventions

See file-conventions.md for:

Project structure and special files
Route segments (dynamic, catch-all, groups)
Parallel and intercepting routes
Middleware rename in v16 (middleware → proxy)

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

Metadata & OG Images

See metadata.md for:

Static and dynamic metadata
```
generateMetadata
```
function
OG image generation with
```
next/og
```
File-based metadata conventions

Image Optimization

See image.md for:

Always use
```
next/image
```
over
```
<img>
```
Remote images configuration
Responsive
```
sizes
```
attribute
Blur placeholders
Priority loading for LCP

Font Optimization

See font.md for:

```
next/font
```
setup
Google Fonts, local fonts
Tailwind CSS integration
Preloading subsets

Bundling

See bundling.md for:

Server-incompatible packages
CSS imports (not link tags)
Polyfills (already included)
ESM/CommonJS issues
Bundle analysis

Scripts

See scripts.md for:

```
next/script
```
vs native script tags
Inline scripts need
```
id
```
Loading strategies
Google Analytics with
```
@next/third-parties
```

Hydration Errors

See hydration-error.md for:

Common causes (browser APIs, dates, invalid HTML)
Debugging with error overlay
Fixes for each cause

Suspense Boundaries

See suspense-boundaries.md for:

CSR bailout with
```
useSearchParams
```
and
```
usePathname
```
Which hooks require Suspense boundaries

Parallel & Intercepting Routes

See parallel-routes.md for:

Modal patterns with
```
@slot
```
and
```
(.)
```
interceptors
```
default.tsx
```
for fallbacks
Closing modals correctly with
```
router.back()
```

Self-Hosting

See self-hosting.md for:

```
output: 'standalone'
```
for Docker
Cache handlers for multi-instance ISR
What works vs needs extra setup

Debug Tricks

See debug-tricks.md for:

MCP endpoint for AI-assisted debugging
Rebuild specific routes with
```
--debug-build-paths
```

next-best-practices

NPX Install

SKILL.md Content