nextjs-best-practices

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 | Static (cached at build) |

| 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
• Use Edge runtime when possible

---

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'
• 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.

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.