developing-nextjs

What this skill does

# Next.js 16 Development

Write concise, targeted, DRY code using modern React 19 and Next.js 16 patterns.

## Next.js 16 Key Changes

### proxy.ts (Replaces middleware.ts)

The `middleware.ts` file is **deprecated**. Use `proxy.ts` instead:

```ts
// proxy.ts (at project root or src/)
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // Runs on Node.js runtime (NOT Edge)
  return NextResponse.redirect(new URL('/home', request.url))
}

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

- `middleware.ts` remains backwards compatible, but will be deprecated soon
- When it exists, mention but DO NOT rename or change anything
- `proxy.ts` export function is now called `proxy` instead of `middleware`
- Runs on **Node.js runtime** (not Edge)
- Config flags renamed: `skipMiddlewareUrlNormalize` → `skipProxyUrlNormalize`

### Async Request APIs (Breaking)

All request APIs must be awaited:

```ts
// Next.js 16 - MUST await
const cookieStore = await cookies()
const headersList = await headers()
const draft = await draftMode()
const { slug } = await params
const query = await searchParams
```

### Turbopack (Default)

Turbopack is now the default bundler. No `--turbopack` flag needed.

```json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}
```

- Use `--webpack` flag to opt out if needed
- Config moved from `experimental.turbopack` to top-level `turbopack`

### Cache Components

New caching model replacing `experimental.ppr`:

```ts
// next.config.ts
const nextConfig = {
  cacheComponents: true,
}
```

Use `"use cache"` directive for explicit caching:

```ts
async function getData() {
  "use cache"
  return await fetchData()
}
```

### New Caching APIs

```ts
import { updateTag, revalidateTag, refresh } from 'next/cache'

// updateTag - read-your-writes semantics (Server Actions only)
export async function updateProfile(userId: string) {
  await db.update(userId)
  updateTag(`user-${userId}`) // User sees changes immediately
}

// revalidateTag - now requires cacheLife profile
revalidateTag('blog-posts', 'max') // SWR behavior with profile

// refresh - refresh uncached data (Server Actions only)
refresh()
```

### React 19.2 Features

- **View Transitions**: Animate navigation/updates
- **`useEffectEvent`**: Extract non-reactive logic from Effects
- **`<Activity>`**: Background rendering with `display: none`

### React Compiler (Stable)

```ts
// next.config.ts
const nextConfig = {
  reactCompiler: true,
}
```

Requires: `bun add -D babel-plugin-react-compiler`

### Other Breaking Changes

- **Node.js 20.9+** required (Node.js 18 dropped)
- **TypeScript 5.1+** required
- **Parallel routes** require explicit `default.js` files
- **`next lint` removed** - use ESLint directly
- **AMP support removed**
- **`next/legacy/image` deprecated** - use `next/image`
- **`images.domains` deprecated** - use `images.remotePatterns`

### next/image Defaults Changed

- `minimumCacheTTL`: 60s → 4 hours
- `imageSizes`: removed `16` from default array
- `qualities`: now `[75]` only by default
- Local images with query strings require `images.localPatterns`

## Coding Standards

### DRY & Conciseness

- Write minimal code solving the problem
- Extract repeated patterns into reusable components/hooks
- Keep files under 300 lines; split when approaching limit
- One component per file unless tightly coupled

### Next.js 16 Patterns

- Use App Router (`app/` directory) exclusively
- Server Components by default; add `'use client'` only when absolutely needed
- Use Server Actions for mutations
- Implement `loading.tsx` and `error.tsx` boundaries
- Use `next/image`, `next/link`, `next/font`

### Tailwind CSS v4

- Use `@import "tailwindcss"` (not v3 directives)
- Configure via `@theme` in CSS, not tailwind.config.js
- Use `bg-linear-to-r` (not `bg-gradient-to-r`)
- Prefer CSS variables over `@apply`

### TypeScript

- Strict typing always
- Use `Id<'tableName'>` for Convex document IDs
- Define explicit return types
- Use `as const` for string literals in unions

## Operational Guidelines

- Read existing codebase and ensure no duplicate code exists
- Make surgical, targeted changes
- Preserve existing patterns in the codebase

## Research Protocol

When encountering unfamiliar Next.js 16 APIs, use Exa and Ref MCP servers (if available) to search examples and official documentation. When unavailable, use web search tools.