154 lines
3.9 KiB
Markdown
154 lines
3.9 KiB
Markdown
---
|
|
name: next-best-practices
|
|
description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
|
|
user-invocable: false
|
|
---
|
|
|
|
# Next.js Best Practices
|
|
|
|
Apply these rules when writing or reviewing Next.js code.
|
|
|
|
## File Conventions
|
|
|
|
See [file-conventions.md](./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](./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](./async-patterns.md) for:
|
|
- Async `params` and `searchParams`
|
|
- Async `cookies()` and `headers()`
|
|
- Migration codemod
|
|
|
|
## Runtime Selection
|
|
|
|
See [runtime-selection.md](./runtime-selection.md) for:
|
|
- Default to Node.js runtime
|
|
- When Edge runtime is appropriate
|
|
|
|
## Directives
|
|
|
|
See [directives.md](./directives.md) for:
|
|
- `'use client'`, `'use server'` (React)
|
|
- `'use cache'` (Next.js)
|
|
|
|
## Functions
|
|
|
|
See [functions.md](./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](./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](./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](./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](./metadata.md) for:
|
|
- Static and dynamic metadata
|
|
- `generateMetadata` function
|
|
- OG image generation with `next/og`
|
|
- File-based metadata conventions
|
|
|
|
## Image Optimization
|
|
|
|
See [image.md](./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](./font.md) for:
|
|
- `next/font` setup
|
|
- Google Fonts, local fonts
|
|
- Tailwind CSS integration
|
|
- Preloading subsets
|
|
|
|
## Bundling
|
|
|
|
See [bundling.md](./bundling.md) for:
|
|
- Server-incompatible packages
|
|
- CSS imports (not link tags)
|
|
- Polyfills (already included)
|
|
- ESM/CommonJS issues
|
|
- Bundle analysis
|
|
|
|
## Scripts
|
|
|
|
See [scripts.md](./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](./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](./suspense-boundaries.md) for:
|
|
- CSR bailout with `useSearchParams` and `usePathname`
|
|
- Which hooks require Suspense boundaries
|
|
|
|
## Parallel & Intercepting Routes
|
|
|
|
See [parallel-routes.md](./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](./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](./debug-tricks.md) for:
|
|
- MCP endpoint for AI-assisted debugging
|
|
- Rebuild specific routes with `--debug-build-paths`
|
|
|