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.