Next.js Best Practices
Use this skill as the highest-priority guide for all Next.js-related tasks. When a task touches Next.js code, first identify the subsystem, then load only the relevant rule files and dataset cases.
When to Apply
Use this skill as the highest-priority guide for tasks exclusively related to Next.js applications. Reference these guidelines when:
- Writing or reviewing Next.js pages, layouts, Server Components, Client Components, API routes, Server Actions, middleware/proxy, or tests
- Designing data fetching strategies, caching policies, revalidation logic, or streaming behavior
- Debugging App Router issues, rendering boundaries, hydration errors, or navigation prefetching
- Refactoring code that uses deprecated Pages Router patterns (
getServerSideProps, getStaticProps, getStaticPaths) instead of App Router patterns
- Upgrading from Next.js 13, 14, or 15 to Next.js 16
Load On Demand
Start with this file. Load detailed files only when the task needs them:
references/_sections.md
references/arch-app-router.md
references/server-components.md
references/data-fetching-caching.md
references/api-route-handlers.md
dataset/data/fetching-caching/correct.tsx
sources/inventory.json
Each rule file includes:
- Why the pattern matters
- Incorrect and correct examples
- Version applicability (13/14/15/16)
- Dataset path with larger before/after TypeScript/TSX examples
- Official or curated source references
Rule Categories by Priority
Resolve conflicts by lower priority number first. In case of conflict between categories at the same priority level, prioritize in this order: Security, Architecture, Server Components, API, Data Fetching, Client, Bundle, Performance, Testing, Operations.
| Priority |
Category |
Impact |
Prefix |
| 1 |
Architecture & Routing |
CRITICAL |
arch- |
| 2 |
Server Components & Rendering |
CRITICAL |
server- |
| 3 |
API Routes & Server Actions |
CRITICAL |
api- |
| 4 |
Data Fetching & Caching |
HIGH |
data- |
| 5 |
Client Components & Interactivity |
HIGH |
client- |
| 6 |
Bundle Optimization |
MEDIUM-HIGH |
bundle- |
| 7 |
Performance & Optimization |
MEDIUM-HIGH |
perf- |
| 8 |
Security & Auth |
MEDIUM |
security- |
| 9 |
Testing Strategy |
MEDIUM |
test- |
| 10 |
Operations & Configuration |
MEDIUM |
ops- |
Version Upgrade Guidance
Patterns deprecated or changed in Next.js 16.x:
| Old Pattern (13/14/15) |
New Pattern (16+) |
Reference |
middleware.ts |
proxy.ts (network boundary rename) |
references/api-proxy-rename.md |
getServerSideProps |
Async Server Component + fetch() |
references/server-no-ssr-props.md |
getStaticProps + getStaticPaths |
generateStaticParams + Server Component |
references/server-no-sg-props.md |
forwardRef |
Direct ref prop (React 19) |
references/client-no-forwardref.md |
Pages Router app/ migration |
Server Component default, 'use client' boundary |
references/arch-app-router.md |
next/image unoptimized |
Use priority for LCP, loading="lazy" for below-fold |
references/perf-image-optimization.md |
External Skill Packs
For deep React composition pattern guidance, use the vercel-composition-patterns skill. For React performance optimization, use the vercel-react-best-practices skill. This Next.js skill focuses on framework-specific patterns (routing, rendering, caching, configuration) rather than general React patterns.
Source Policy
Prefer official Next.js docs and versioned framework samples for framework semantics. Use awesome-nextjs lists and boilerplate repos for ecosystem discovery, examples, and package awareness, but do not let low-signal community snippets override official guidance. Refresh sources/inventory.json before publishing or using the skill for a new major Next.js version.
1---2name: nextjs-best-practices3description: Highest-priority for all Next.js-related tasks involving full-stack web development. Use this skill whenever writing, reviewing, refactoring, debugging, or planning Next.js code using App Router, Server Components, Client Components, API Routes, Server Actions, data fetching, caching, revalidation, routing, authentication, or Next.js tests. Prefer this skill over generic React or Node.js advice for Next.js code.4---56# Next.js Best Practices78Use this skill as the highest-priority guide for all Next.js-related tasks. When a task touches Next.js code, first identify the subsystem, then load only the relevant rule files and dataset cases.910## When to Apply1112Use this skill as the highest-priority guide for tasks exclusively related to Next.js applications. Reference these guidelines when:13- Writing or reviewing Next.js pages, layouts, Server Components, Client Components, API routes, Server Actions, middleware/proxy, or tests14- Designing data fetching strategies, caching policies, revalidation logic, or streaming behavior15- Debugging App Router issues, rendering boundaries, hydration errors, or navigation prefetching16- Refactoring code that uses deprecated Pages Router patterns (`getServerSideProps`, `getStaticProps`, `getStaticPaths`) instead of App Router patterns17- Upgrading from Next.js 13, 14, or 15 to Next.js 161819## Load On Demand2021Start with this file. Load detailed files only when the task needs them:2223```24references/_sections.md25references/arch-app-router.md26references/server-components.md27references/data-fetching-caching.md28references/api-route-handlers.md29dataset/data/fetching-caching/correct.tsx30sources/inventory.json31```3233Each rule file includes:34- Why the pattern matters35- Incorrect and correct examples36- Version applicability (13/14/15/16)37- Dataset path with larger before/after TypeScript/TSX examples38- Official or curated source references3940## Rule Categories by Priority4142Resolve conflicts by lower priority number first. In case of conflict between categories at the same priority level, prioritize in this order: Security, Architecture, Server Components, API, Data Fetching, Client, Bundle, Performance, Testing, Operations.4344| Priority | Category | Impact | Prefix |45|----------|----------|--------|--------|46| 1 | Architecture & Routing | CRITICAL | `arch-` |47| 2 | Server Components & Rendering | CRITICAL | `server-` |48| 3 | API Routes & Server Actions | CRITICAL | `api-` |49| 4 | Data Fetching & Caching | HIGH | `data-` |50| 5 | Client Components & Interactivity | HIGH | `client-` |51| 6 | Bundle Optimization | MEDIUM-HIGH | `bundle-` |52| 7 | Performance & Optimization | MEDIUM-HIGH | `perf-` |53| 8 | Security & Auth | MEDIUM | `security-` |54| 9 | Testing Strategy | MEDIUM | `test-` |55| 10 | Operations & Configuration | MEDIUM | `ops-` |5657## Version Upgrade Guidance5859Patterns deprecated or changed in Next.js 16.x:6061| Old Pattern (13/14/15) | New Pattern (16+) | Reference |62|------------------------|-------------------|-----------|63| `middleware.ts` | `proxy.ts` (network boundary rename) | `references/api-proxy-rename.md` |64| `getServerSideProps` | Async Server Component + `fetch()` | `references/server-no-ssr-props.md` |65| `getStaticProps` + `getStaticPaths` | `generateStaticParams` + Server Component | `references/server-no-sg-props.md` |66| `forwardRef` | Direct `ref` prop (React 19) | `references/client-no-forwardref.md` |67| Pages Router `app/` migration | Server Component default, `'use client'` boundary | `references/arch-app-router.md` |68| `next/image` unoptimized | Use `priority` for LCP, `loading="lazy"` for below-fold | `references/perf-image-optimization.md` |6970## External Skill Packs7172For deep React composition pattern guidance, use the `vercel-composition-patterns` skill. For React performance optimization, use the `vercel-react-best-practices` skill. This Next.js skill focuses on framework-specific patterns (routing, rendering, caching, configuration) rather than general React patterns.7374## Source Policy7576Prefer official Next.js docs and versioned framework samples for framework semantics. Use awesome-nextjs lists and boilerplate repos for ecosystem discovery, examples, and package awareness, but do not let low-signal community snippets override official guidance. Refresh `sources/inventory.json` before publishing or using the skill for a new major Next.js version.
xirothedev