Nextjs

---
name: nextjs
description: "Covers Next.js across supported versions (15 and 16): the rendering pipeline, caching model, Server Actions, middleware/proxy, data fetching, image/font optimization, Turbopack, and deployment (Vercel + self-hosting). Use for \"Next.js\", \"nextjs\", \"next.js\", \"Pages Router\", \"Server Actions\", \"next/image\", \"next/font\", \"Turbopack\", \"ISR\", \"SSR Next\", \"SSG Next\", \"Next.js 15\", \"Next.js 16\", \"getServerSideProps\", \"generateStaticParams\" questions. Covers App Router basics; for deep App Router routing questions (parallel routes, intercepting routes, nested layouts) use the `nextjs-app-router` skill instead."
license: MIT
---

# Next.js

This skill covers Next.js across supported versions (15 and 16), including:

- App Router architecture (file-system routing, nested layouts, parallel routes, intercepting routes)
- Rendering pipeline (Server Components, Client Components, RSC payload, streaming, hydration)
- Caching model (request memoization, Data Cache, Full Route Cache, Router Cache)
- Server Actions (mutations, progressive enhancement, revalidation, security)
- Middleware and proxy (Edge Runtime middleware.ts in v15, Node.js proxy.ts in v16)
- Data fetching (Server Component fetch, generateStaticParams, ISR, Route Handlers)
- Image optimization (next/image, responsive sizes, AVIF/WebP, blur placeholders)
- Font optimization (next/font/google, next/font/local, zero-layout-shift loading)
- Turbopack (Rust-based bundler, HMR, incremental compilation, file system caching)
- Metadata API (static, dynamic, templates, sitemap, robots)
- Deployment (Vercel zero-config, standalone self-hosting, Docker, custom cache handlers)
- React Compiler integration (automatic memoization, v16 opt-in)
- Cache Components ("use cache" directive, cacheLife, cacheTag, v16)

For React core concepts (hooks, components, virtual DOM, context, Suspense internals), see the `react` skill. This skill focuses on Next.js-specific routing, rendering, caching, and deployment.

When a question is version-specific, read the matching file under `references/versions/`. When the version is unknown, give general guidance and note where behavior differs across versions.

## How to Approach Tasks

When you receive a request:

1. **Classify** the request type:
   - **Troubleshooting** -- Load `references/diagnostics.md`
   - **Optimization** -- Load `references/best-practices.md`
   - **Architecture** -- Load `references/architecture.md`
   - **Routing** -- Use the `nextjs-app-router` skill
   - **Data fetching / caching** -- Load `references/patterns/data-fetching.md`
   - **Authentication** -- Load `references/patterns/authentication.md`
   - **Deployment** -- Load `references/patterns/deployment.md`

2. **Identify version** -- Determine which Next.js version the user is running. If unclear, ask. Version matters for caching defaults, API signatures, bundler behavior, and available features.

3. **Load context** -- Read the relevant reference file for deep knowledge.

4. **Analyze** -- Apply Next.js-specific reasoning, not generic React advice. Consider the rendering model, caching layers, and server/client boundary.

5. **Recommend** -- Provide actionable, specific guidance with code examples.

6. **Verify** -- Suggest validation steps (build output analysis, bundle analyzer, dev tools, Web Vitals checks).

## Core Expertise

### App Router

The App Router is the primary routing system (stable since v13.4, fully featured in v15/v16). Routes live under `app/`; each folder represents a route segment. Special files (`page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`, `template.tsx`, `default.tsx`, `route.ts`) activate framework behavior.

For comprehensive routing guidance, use the `nextjs-app-router` skill.

```
app/
  layout.tsx          <- Root layout (wraps everything, must include <html>/<body>)
  page.tsx            <- Homepage
  dashboard/
    layout.tsx        <- Dashboard layout (persists across child navigations)
    page.tsx          <- /dashboard
    settings/
      page.tsx        <- /dashboard/settings
```

Layouts are hierarchical and persistent -- they do not re-render when navigating between sibling routes. Route groups `(groupName)` organize routes without affecting URL paths. Parallel routes `@slotName` render multiple pages simultaneously.

### Rendering Pipeline

All components in `app/` are React Server Components (RSC) by default. They run on the server only, produce no client-side JavaScript, and can directly access databases, file systems, and secrets.

Client Components opt in with `"use client"` at the top of the file. This creates a boundary -- the component and all its imports are included in the client bundle.

The rendering flow:
1. Server renders RSC tree -> RSC payload (compact streaming format)
2. RSC payload + Client Component tree -> HTML string (SSR)
3. HTML streams to browser (early bytes paint fast)
4. Browser renders HTML immediately (no JS needed for initial paint)
5. React loads, reads RSC payload, hydrates Client Component boundaries

Streaming with `<Suspense>` sends content progressively -- fast components appear while slow ones still load. `loading.tsx` provides automatic Suspense boundaries per route segment.

### Caching Model

Next.js has four distinct caching layers:

| Layer | Scope | Purpose |
|---|---|---|
| Request Memoization | Single request | Deduplicates identical `fetch()` calls within one render tree |
| Data Cache | Persistent across requests | Caches `fetch()` responses server-side |
| Full Route Cache | Persistent (build/revalidation) | Caches complete HTML + RSC payload for static routes |
| Router Cache | Browser session | Caches visited/prefetched route segments client-side |

**Critical version difference:** v14 cached `fetch()` by default (`force-cache`); v15+ does NOT cache by default (`no-store`). Code relying on implicit v14 caching must add explicit cache options when upgrading.

In v16, the `"use cache"` directive provides fine-grained, function-level caching via Cache Components, replacing route-level static/dynamic choices.

### Server Actions

Async functions marked with `"use server"` that execute on the server. They are the primary mutation pattern in the App Router.

```tsx
// app/actions.ts
"use server";

export async function createInvoice(formData: FormData) {
  const amount = formData.get("amount");
  await db.invoices.create({ data: { amount } });
  revalidatePath("/dashboard/invoices");
}
```

Key behaviors:
- Become POST requests under the hood with cryptographically random action IDs
- Progressive enhancement: `<form action={serverAction}>` works without JavaScript
- Always validate and authorize within the action body
- Use `revalidatePath()` / `revalidateTag()` to invalidate cached data after mutations
- Use `redirect()` to navigate after mutation (throws internally, do not wrap in try/catch)

### Middleware and Proxy

Runs before route matching and before cache is checked. Use for authentication, redirects, header injection, A/B testing, geolocation.

| Version | Runtime | File |
|---|---|---|
| v15 | Edge Runtime (V8 isolates) | `middleware.ts` at project root |
| v16 | Node.js Runtime (full APIs) | `proxy.ts` at project root |

v16's `proxy.ts` runs on the full Node.js runtime, enabling native `crypto`, `fs`, `net`, third-party Node.js libraries, and direct database connections. `middleware.ts` is deprecated in v16 but not yet removed.

See `assets/proxy.ts` for an annotated example.

### Data Fetching

**Server Components fetch** -- the primary pattern. Extended by Next.js with caching controls:

```tsx
// Fetch in Server Component (v15+ default: no-store)
const products = await fetch("https://api.example.com/products").then(r => r.json());

// With explicit caching
const config = await fetch("https://api.example.com/config", {
  cache: "force-cache",
  next: { tags: ["config"] },
}).then(r => r.json());
```

**generateStaticParams** -- pre-render dynamic routes at build time (SSG/ISR).

**Route Handlers** -- `route.ts` files in `app/` replace Pages Router API routes. Support GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

**ORM / Database access** -- Server Components can query databases directly without an API layer.

See `references/patterns/data-fetching.md` for comprehensive patterns.

### Image and Font Optimization

**next/image**: Automatic optimization with lazy loading, responsive `sizes`/`srcset`, AVIF/WebP format negotiation, blur placeholders, and CDN support. Use `priority` for LCP images. Configure `images.remotePatterns` for external sources.

**next/font/google** and **next/font/local**: Zero-layout-shift font loading. Fonts are self-hosted at build time -- no external requests at runtime. Variable fonts supported. Use CSS variables for Tailwind integration.

### Turbopack

Rust-based incremental bundler built as the successor to webpack:

| Version | Dev | Production |
|---|---|---|
| Next.js 15 | Stable (`--turbo` flag) | Alpha |
| Next.js 16 | Stable (default) | Stable (default) |

Key characteristics:
- Near-instant HMR -- only changed modules recompiled
- Significantly faster cold starts (often 10x+ vs webpack for large projects)
- File system caching (v16 beta) persists compiler artifacts across restarts
- Does not run webpack plugins/loaders directly; uses built-in transforms
- Auto-detects Babel config and applies transforms (prefer SWC where possible)

### Deployment

**Vercel** -- zero-config reference platform with automatic ISR, Edge Functions, image optimization CDN, preview deployments, and Web Vitals analytics.

**Self-hosting** -- use `output: "standalone"` to produce a minimal Node.js server. Copy `public/` and `.next/static/` alongside the standalone output. Configure custom cache handlers for ISR with Redis or other backends.

**Build Adapters** (v16 alpha) -- low-level API for custom deployment targets (Cloudflare Workers, Deno Deploy, etc.).

See `references/patterns/deployment.md` for Vercel vs self-hosting comparison, Docker configuration, and ISR on self-hosted.

## Common Pitfalls

**1. Making an entire page a Client Component for one interactive element**
Push `"use client"` as far down the component tree as possible. Extract interactive islands into small Client Components; keep the parent as a Server Component for reduced bundle size and server-side data access.

**2. Missing `await` on async APIs in v15+**
`cookies()`, `headers()`, `params`, and `searchParams` are async in v15 and async-only in v16. Synchronous access causes deprecation warnings (v15) or runtime errors (v16). Run the codemod: `npx @next/codemod@canary next-async-request-api .`

**3. Relying on implicit caching after upgrading from v14**
v15 reversed caching defaults -- `fetch()` is `no-store` by default. Audit all `fetch()` calls and add explicit `cache: "force-cache"` or `next: { revalidate }` where caching is needed.

**4. Forgetting `revalidatePath`/`revalidateTag` after Server Action mutations**
After a database write in a Server Action, the UI shows stale data unless you explicitly invalidate the relevant cached paths or tags. Always call `revalidatePath()` or `revalidateTag()` after mutations.

**5. Using `chcon`-style temporary fixes instead of proper server/client boundaries**
Importing a Server Component into a Client Component tree silently converts it to a Client Component. Pass Server Components as `children` props into Client Components to preserve server-side rendering.

**6. Hydration mismatch from dynamic values**
Server-rendered HTML must match client render output. Dynamic values (dates, `Math.random()`, browser-only state) cause hydration errors. Use `suppressHydrationWarning` sparingly, or wrap browser-only content in `useEffect` or `dynamic(() => import("..."), { ssr: false })`.

**7. `redirect()` inside try/catch**
`redirect()` throws internally to trigger navigation. Wrapping it in try/catch swallows the redirect. Call `redirect()` outside try/catch blocks, or re-throw if the redirect error is caught.

**8. Middleware timeout on complex auth logic (v15)**
Edge Runtime has a 30-second timeout with no Node.js APIs. Offload heavy computation to Route Handlers or upgrade to v16's `proxy.ts` which runs on full Node.js.

**9. Missing `default.tsx` in parallel route slots**
When a parallel route slot has no matching route for the current URL, Next.js requires `default.tsx` as a fallback. Without it, the entire page 404s. Add `default.tsx` returning `null` to each slot.

**10. Using `template.tsx` when `layout.tsx` is intended**
`template.tsx` re-mounts on every navigation, resetting state and re-running effects. Use `layout.tsx` for persistent shared UI (nav bars, sidebars). Reserve `template.tsx` for intentional per-navigation behavior (entry animations, per-page analytics).

## Version-Specific Guidance

| Version | Reference | What's version-specific |
|---|---|---|
| 15 | `references/versions/15.md` | Turbopack dev stable, React 19 support, async request APIs (breaking), caching defaults reversed (breaking), Form component, instrumentation stable, Server Actions security, self-hosting improvements, v14-to-v15 migration |
| 16 | `references/versions/16.md` | Turbopack prod stable (default), React Compiler integration, Cache Components ("use cache"), proxy.ts replaces middleware.ts, new caching APIs (updateTag, refresh), React 19.2 features (View Transitions, Activity, useEffectEvent), removed features (AMP, next lint), v15-to-v16 migration |

## Sibling Skill

For deep routing expertise, use the `nextjs-app-router` skill: complete routing model, layouts, parallel routes, intercepting routes, data fetching patterns, authentication, internationalization, Pages Router to App Router migration, routing diagnostics.

## Reference Files

Load these when you need deep knowledge for a specific area:

- `references/architecture.md` -- App Router model, rendering pipeline, caching layers, Server Actions, middleware, data fetching, Turbopack, metadata. Read for "how does X work" questions.
- `references/best-practices.md` -- Image/font optimization, self-hosting, project organization, performance optimization, instrumentation. Read for design and optimization questions.
- `references/diagnostics.md` -- Build errors, caching gotchas, hydration issues, bundle analysis, Core Web Vitals. Read when troubleshooting.

## Configuration References

- `assets/next.config.ts` -- Annotated Next.js 16 configuration (Turbopack, React Compiler, Cache Components, images, custom cache profiles)
- `assets/tsconfig.json` -- Next.js TypeScript config with path aliases
- `assets/proxy.ts` -- Annotated proxy.ts example replacing middleware.ts (v16)

## Pattern Guides

- `references/patterns/data-fetching.md` -- Server Components fetch, Server Actions, Cache Components, ISR, Route Handlers
- `references/patterns/authentication.md` -- NextAuth/Auth.js, middleware/proxy auth, session patterns, cascading auth checks
- `references/patterns/deployment.md` -- Vercel vs self-hosting, standalone output, Docker, ISR on self-hosted, Build Adapters

## Diagnostic Scripts

Ready-made build audit (read-only) in `scripts/`.

- `scripts/01-build-and-config-audit.sh` -- Per-route bundle sizes, render-strategy sanity, middleware/proxy check