Nextjs Development

Next.js Development - Comprehensive Guide

A unified skill merging best practices for Next.js development, covering App Router patterns, Server Components, data fetching, caching strategies, and module architecture.

---

When to Use This Skill

• Creating new Next.js pages, layouts, or components
• Implementing data fetching (Server Components, TanStack Query, SWR)
• Deciding between Server and Client Components
• Building Server Actions for forms and mutations
• Implementing caching strategies (ISR, "use cache", revalidation)
• Setting up routing with App Router
• Migrating from Next.js 15 to 16
• Building complete feature modules with CRUD operations
• Optimizing metadata and SEO
• Styling with Tailwind CSS

When NOT to Use

• Generic React patterns, hooks, or component logic (use react-development)
• UI/CSS design systems or visual styling (use frontend-design)
• Backend API development without Next.js (use python-development or relevant backend skill)
• Build tool configuration unrelated to Next.js (use relevant bundler skill)

Decision Tree

What Next.js problem are you solving?
│
├─ Server vs Client Component?
│  ├─ Needs interactivity (onClick, onChange)? → Client Component ('use client')
│  ├─ Needs React hooks (useState, useEffect)? → Client Component
│  ├─ Needs browser APIs (window, localStorage)? → Client Component
│  ├─ Needs to fetch data? → Server Component (preferred)
│  └─ None of the above? → Server Component (default)
│
├─ Data fetching strategy?
│  ├─ Data needed at build time? → SSG (generateStaticParams + fetch with force-cache)
│  ├─ Data needed at request time? → SSR (fetch with no-store)
│  ├─ Data revalidated periodically? → ISR (next: { revalidate: N })
│  ├─ Data fetched on client? → TanStack Query with useSuspenseQuery
│  └─ Streaming/progressive loading? →  boundary wrapping async component
│
├─ Caching strategy?
│  ├─ Static page, rarely changes? → 'force-cache' or SSG
│  ├─ Dynamic page, always fresh? → 'no-store'
│  ├─ Revalidate on a schedule? → next: { revalidate: N }
│  ├─ Revalidate on demand? → next: { tags: [...] } + revalidateTag()
│  └─ Cache component output? → 'use cache' directive (Next.js 16)
│
├─ Form/mutation handling?
│  ├─ Simple form submit? → Server Action with 'use server'
│  ├─ Need loading state? → useFormStatus()
│  ├─ Need optimistic UI? → useOptimistic()
│  └─ Need client validation? → Zod schema + client-side validation before submit
│
└─ Next.js version concerns?
   ├─ Using Next.js 16? → Use async params, proxy.ts, "use cache"
   ├─ Migrating 15→16? → See Next.js 16 Breaking Changes below
   └─ Using Next.js 13/14/15? → Use sync params, middleware.ts

---

Critical Rules

These rules are NON-NEGOTIABLE. Violations will break builds or cause runtime errors.

1. ALWAYS use ` from next/image`

// CORRECT
import Image from 'next/image'

// WRONG - BUILD WILL FAIL

2. Server Components are DEFAULT

Only add 'use client' when the component needs:

• React hooks (useState, useEffect, etc.)
• Event handlers (onClick, onChange, etc.)
• Browser APIs (window, localStorage, etc.)

3. Never make async Client Components

4. Always specify cache strategy for fetch()

const data = await fetch('/api/data', { cache: 'no-store' })
const data = await fetch('/api/data', { cache: 'force-cache' })
const data = await fetch('/api/data', { next: { revalidate: 3600 } })

5. Await async APIs in Next.js 16

// CORRECT (Next.js 16)
export default async function Page({ params }: { params: Promise }) {
  const { id } = await params
  const cookieStore = await cookies()
  const headersList = await headers()
}

---

Next.js 16 Breaking Changes

1. Async Route Parameters

params, searchParams, cookies(), headers(), and draftMode() are now async.

export default async function Page({
  params,
  searchParams,
}: {
  params: Promise
  searchParams: Promise
}) {
  const { slug } = await params
  const { query } = await searchParams
  return {slug}
}

2. Middleware to Proxy Migration

middleware.ts is deprecated. Use proxy.ts instead.

// proxy.ts (NEW)
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  const token = request.cookies.get('token')
  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  return NextResponse.next()
}

export const config = {
  matcher: '/dashboard/:path*',
}

3. Parallel Routes Require default.js

4. Cache Components with "use cache"

'use cache'

export async function ExpensiveComponent() {
  const data = await fetch('https://api.example.com/data')
  return {data}
}

5. Updated revalidateTag() API

revalidateTag('posts', 'max')
// Cache life profiles: 'max', 'hours', 'days', 'weeks', 'default'

---

Server vs Client Components - Decision Tree

Do you need interactivity (onClick, onChange)?
├─ YES → Client Component ('use client')
└─ NO → Server Component (default)

Do you need React hooks (useState, useEffect)?
├─ YES → Client Component
└─ NO → Server Component

Do you need browser APIs (window, localStorage)?
├─ YES → Client Component
└─ NO → Server Component

Do you need to fetch data?
├─ Use Server Component (preferred)
└─ Client Component only if data must be client-side

---

App Router File Conventions

app/
  layout.tsx       # Root layout (required)
  page.tsx         # Home page (/)
  loading.tsx      # Loading UI
  error.tsx        # Error boundary
  not-found.tsx    # 404 page
  template.tsx     # Re-rendered layout

  blog/
    layout.tsx     # Blog layout
    page.tsx       # /blog
    [slug]/
      page.tsx     # /blog/[slug]

  (marketing)/     # Route group (no URL effect)
    about/page.tsx # /about

  @modal/          # Parallel route
    login/page.tsx
    default.tsx    # Required fallback

  api/
    users/route.ts # API route

---

Data Fetching Quick Reference

• Server Components: async/await with fetch() or direct DB calls (preferred)
• Parallel fetching: Promise.all([...]) for multiple requests
• Streaming: Wrap async components in `` for progressive loading
• Client-side: TanStack Query useSuspenseQuery for client-fetched data
• Caching: cache: 'no-store' | cache: 'force-cache' | next: { revalidate: N } | next: { tags: [...] }

---

Server Actions Quick Reference

• Mark with 'use server' directive
• Use formData.get() for form fields
• Validate with Zod: schema.safeParse()
• Call revalidateTag() / revalidatePath() after mutations
• Use useFormStatus() for loading states
• Use useOptimistic() for optimistic UI updates

---

Anti-Patterns

| Anti-Pattern | Problem | Solution | |---|---|---| | Adding 'use client' to every component | Loses Server Component benefits; larger JS bundle | Only add 'use client' when hooks, events, or browser APIs are needed | | Using ` instead of | Build fails; no optimization | Always import from next/image | | Fetching data in Client Components by default | Unnecessary client-side waterfall | Prefer Server Component data fetching; only use client fetch for dynamic user-driven queries | | Missing cache strategy on fetch() | Default varies by Next.js version; unpredictable | Always specify cache or next.revalidate explicitly | | Not awaiting params in Next.js 16 | Runtime error: params is a Promise | const { id } = await params — always await in Next.js 16 | | Making Client Components async | Runtime error — async client components are not supported | Fetch data in Server Component, pass as props to Client Component | | Missing default.tsx for parallel routes | Error when parallel route has no match | Always create default.tsx alongside parallel route page.tsx | | Server Actions without input validation | Malformed data reaches your server | Always validate with Zod before processing | | Using middleware.ts in Next.js 16 | Deprecated; will be removed | Migrate to proxy.ts | | Skipping revalidateTag/revalidatePath after mutations | Stale data shown after form submit | Always call revalidation after Server Action mutations | | Deep component trees of Client Components | Heavy JS bundle, slow hydration | Push 'use client'` down to leaf components; keep parents as Server Components |

---

Module Architecture (5-Layer Pattern)

app/(routes)/[module]/       # Pages (list, detail, create, edit)
lib/services/[module]/       # Service layer (data access)
hooks/[module]/              # Custom hooks
types/                       # TypeScript interfaces & DTOs
_components/                 # Feature-specific components

See [Extended Patterns](references/extended-patterns.md) for detailed code examples of all patterns above.

---

Resources

Reference Files

• references/extended-patterns.md - Detailed code examples for all patterns
• references/architecture-patterns.md - Overall architecture
• references/component-patterns.md - Component patterns
• references/database-patterns.md - Database schema and RLS
• references/hooks-patterns.md - Custom hooks
• references/page-patterns.md - Page structure
• references/permission-patterns.md - Permission system
• references/service-patterns.md - Service layer
• references/typescript-patterns.md - TypeScript patterns
• references/next-16-migration-guide.md - Migration guide
• references/top-errors.md - Common errors and solutions

Resource Files

• resources/app-router-complete.md - App Router guide
• resources/caching-strategies.md - Caching deep dive
• resources/data-fetching-complete.md - Data fetching patterns
• resources/metadata-api.md - Metadata API guide
• resources/server-actions-complete.md - Server Actions guide
• resources/rendering-strategies.md - SSG, ISR, SSR, Streaming
• resources/routing-patterns.md - Routing patterns
• resources/server-client-decision.md - Server/Client decision guide

Templates

• templates/app-router-async-params.tsx - Async params pattern
• templates/cache-component-use-cache.tsx - Cache Components
• templates/parallel-routes-with-default.tsx - Parallel routes
• templates/proxy-migration.ts - Proxy migration
• templates/route-handler-api.ts - Route handlers
• templates/server-actions-form.tsx - Server Actions forms
• templates/layout-template.md - Layout templates
• templates/page-template.md - Page templates

Scripts

• scripts/analyze-routing-structure.mjs - Analyze routing
• scripts/check-versions.sh - Check versions
• scripts/validate-patterns.py - Validate Next.js patterns

Official Documentation

• Next.js Docs
• React Docs
• Tailwind CSS Docs

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: viktorbezdek
• Source: viktorbezdek/skillstack
• License: MIT

Install and usage instructions live in the source repository linked above.