Next Best Practices

1---
2name: next-best-practices
3description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
4user-invocable: false
5---
6 
7# Next.js Best Practices
8 
9Apply these rules when writing or reviewing Next.js code.
10 
11## File Conventions
12 
13See [file-conventions.md](./file-conventions.md) for:
14- Project structure and special files
15- Route segments (dynamic, catch-all, groups)
16- Parallel and intercepting routes
17- Middleware rename in v16 (middleware → proxy)
18 
19## RSC Boundaries
20 
21Detect invalid React Server Component patterns.
22 
23See [rsc-boundaries.md](./rsc-boundaries.md) for:
24- Async client component detection (invalid)
25- Non-serializable props detection
26- Server Action exceptions
27 
28## Async Patterns
29 
30Next.js 15+ async API changes.
31 
32See [async-patterns.md](./async-patterns.md) for:
33- Async `params` and `searchParams`
34- Async `cookies()` and `headers()`
35- Migration codemod
36 
37## Runtime Selection
38 
39See [runtime-selection.md](./runtime-selection.md) for:
40- Default to Node.js runtime
41- When Edge runtime is appropriate
42 
43## Directives
44 
45See [directives.md](./directives.md) for:
46- `'use client'`, `'use server'` (React)
47- `'use cache'` (Next.js)
48 
49## Functions
50 
51See [functions.md](./functions.md) for:
52- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
53- Server functions: `cookies`, `headers`, `draftMode`, `after`
54- Generate functions: `generateStaticParams`, `generateMetadata`
55 
56## Error Handling
57 
58See [error-handling.md](./error-handling.md) for:
59- `error.tsx`, `global-error.tsx`, `not-found.tsx`
60- `redirect`, `permanentRedirect`, `notFound`
61- `forbidden`, `unauthorized` (auth errors)
62- `unstable_rethrow` for catch blocks
63 
64## Data Patterns
65 
66See [data-patterns.md](./data-patterns.md) for:
67- Server Components vs Server Actions vs Route Handlers
68- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
69- Client component data fetching
70 
71## Route Handlers
72 
73See [route-handlers.md](./route-handlers.md) for:
74- `route.ts` basics
75- GET handler conflicts with `page.tsx`
76- Environment behavior (no React DOM)
77- When to use vs Server Actions
78 
79## Metadata & OG Images
80 
81See [metadata.md](./metadata.md) for:
82- Static and dynamic metadata
83- `generateMetadata` function
84- OG image generation with `next/og`
85- File-based metadata conventions
86 
87## Image Optimization
88 
89See [image.md](./image.md) for:
90- Always use `next/image` over `<img>`
91- Remote images configuration
92- Responsive `sizes` attribute
93- Blur placeholders
94- Priority loading for LCP
95 
96## Font Optimization
97 
98See [font.md](./font.md) for:
99- `next/font` setup
100- Google Fonts, local fonts
101- Tailwind CSS integration
102- Preloading subsets
103 
104## Bundling
105 
106See [bundling.md](./bundling.md) for:
107- Server-incompatible packages
108- CSS imports (not link tags)
109- Polyfills (already included)
110- ESM/CommonJS issues
111- Bundle analysis
112 
113## Scripts
114 
115See [scripts.md](./scripts.md) for:
116- `next/script` vs native script tags
117- Inline scripts need `id`
118- Loading strategies
119- Google Analytics with `@next/third-parties`
120 
121## Hydration Errors
122 
123See [hydration-error.md](./hydration-error.md) for:
124- Common causes (browser APIs, dates, invalid HTML)
125- Debugging with error overlay
126- Fixes for each cause
127 
128## Suspense Boundaries
129 
130See [suspense-boundaries.md](./suspense-boundaries.md) for:
131- CSR bailout with `useSearchParams` and `usePathname`
132- Which hooks require Suspense boundaries
133 
134## Parallel & Intercepting Routes
135 
136See [parallel-routes.md](./parallel-routes.md) for:
137- Modal patterns with `@slot` and `(.)` interceptors
138- `default.tsx` for fallbacks
139- Closing modals correctly with `router.back()`
140 
141## Self-Hosting
142 
143See [self-hosting.md](./self-hosting.md) for:
144- `output: 'standalone'` for Docker
145- Cache handlers for multi-instance ISR
146- What works vs needs extra setup
147 
148## Debug Tricks
149 
150See [debug-tricks.md](./debug-tricks.md) for:
151- MCP endpoint for AI-assisted debugging
152- Rebuild specific routes with `--debug-build-paths`
153 
154