Next.js Best Practices
Principles for Next.js App Router development.
1. Server vs Client Components
Decision Tree
Does it need...?
│
├── useState, useEffect, event handlers
│ └── Client Component ('use client')
│
├── Direct data fetching, no interactivity
│ └── Server Component (default)
│
└── Both?
└── Split: Server parent + Client child
By Default
| Type | Use |
|---|
| Server | Data fetching, layout, static content |
| Client | Forms, buttons, interactive UI |
2. Data Fetching Patterns
Fetch Strategy
| Pattern | Use |
|---|
| Default | Version/config dependent; current fetch defaults are uncached |
| Explicit cache | fetch(url, { cache: "force-cache" }) when data may be shared |
| Revalidate | ISR (time-based refresh) |
| No-store | Dynamic (every request) |
Data Flow
| Source | Pattern |
|---|
| Database | Server Component fetch |
| API | fetch with caching |
| User input | Client state + server action |
3. Routing Principles
File Conventions
| File | Purpose |
|---|
page.tsx | Route UI |
layout.tsx | Shared layout |
loading.tsx | Loading state |
error.tsx | Error boundary |
not-found.tsx | 404 page |
Route Organization
| Pattern | Use |
|---|
Route groups (name) | Organize without URL |
Parallel routes @slot | Multiple same-level pages |
Intercepting (.) | Modal overlays |
4. API Routes
Route Handlers
| Method | Use |
|---|
| GET | Read data |
| POST | Create data |
| PUT/PATCH | Update data |
| DELETE | Remove data |
Best Practices
- Validate input with Zod
- Return proper status codes
- Handle errors gracefully
- Choose Node.js or Edge runtime according to dependency and deployment support; do not assume Node APIs are available on Edge
5. Performance Principles
Image Optimization
- Use next/image component
- Set priority for above-fold
- Provide blur placeholder
- Use responsive sizes
Bundle Optimization
- Dynamic imports for heavy components
- Route-based code splitting (automatic)
- Analyze with bundle analyzer
6. Metadata
Static vs Dynamic
| Type | Use |
|---|
| Static export | Fixed metadata |
| generateMetadata | Dynamic per-route |
Essential Tags
- title (50-60 chars)
- description (150-160 chars)
- Open Graph images
- Canonical URL
7. Caching Strategy
Cache Layers
| Layer | Control |
|---|
| Request | fetch options |
| Data | revalidate/tags |
| Full route | route config |
Revalidation
| Method | Use |
|---|
| Time-based | revalidate: 60 |
| On-demand | revalidatePath/Tag |
| No cache | no-store |
8. Server Actions
Use Cases
- Form submissions
- Data mutations
- Revalidation triggers
Best Practices
- Mark with 'use server'
- Authenticate and authorize each action/handler on the server; exported actions are callable endpoints
- Validate all inputs
- Return typed responses
- Handle errors
9. Anti-Patterns
| ❌ Don't | ✅ Do |
|---|
| 'use client' everywhere | Server by default |
| Fetch in client components | Fetch in server |
| Skip loading states | Use loading.tsx |
| Ignore error boundaries | Use error.tsx |
| Large client bundles | Dynamic imports |
10. Project Structure
app/
├── (marketing)/ # Route group
│ └── page.tsx
├── (dashboard)/
│ ├── layout.tsx # Dashboard layout
│ └── page.tsx
├── api/
│ └── [resource]/
│ └── route.ts
└── components/
└── ui/
Remember: Server Components are the default for a reason. Start there, add client only when needed.
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Version scope
Check the installed Next.js version and whether Cache Components is enabled before applying caching advice. The official caching guide distinguishes these models. Test freshness and invalidation explicitly; never put user-specific secrets or authorization-dependent responses into a shared cache.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
