/nextjs-best-practices

name: nextjs-best-practices
description: "Next.js App Router principles. Server Components, data fetching, routing patterns."
risk: unknown
source: community
date_added: "2026-02-27"

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.