nextjs-16-proxy-patterns
Next.js 16 代理模式的指南,替代了已弃用的中间件功能。涵盖新的 proxy.ts 文件约定、异步请求 API 和适当的请求拦截。在实现认证、重定向、头部修改或网络边界级别的请求处理时使用。
📖 中文导读:Next.js 16 代理模式的指南,替代了已弃用的中间件功能。涵盖新的 proxy.ts 文件约定、异步请求 API 和适当的请求拦截。在实现认证、重定向、头部修改或网络边界级别的请求处理时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: nextjs-16-proxy-patterns description: Guide for Next.js 16 proxy patterns, replacing the deprecated middleware functionality. Covers the new proxy.ts file convention, async request APIs, and proper request interception. Use when implementing authentication, redirects, headers modification, or request processing at the network boundary level. allowed-tools: Read, Write, Edit, Glob, Grep, Bash
Next.js 16: Proxy Patterns
Overview
In Next.js 16, the middleware file convention has been renamed to proxy to clarify network boundary and routing focus. This change affects how you intercept and modify requests before they reach your application.
Next.js 16 Breaking Changes
⚠️ CRITICAL: This is a breaking change in Next.js 16:
- File Renaming:
middleware.ts→proxy.ts - Function Renaming:
export function middleware()→export function proxy() - Runtime Change: Proxy runs in
nodejsruntime (notedgeruntime) - Config Updates:
skipMiddlewareUrlNormalize→skipProxyUrlNormalize
When to Use This Skill
Use this skill when:
- Setting up request interception (authentication, redirects, headers)
- Replacing old middleware functionality with proxy
- Implementing authentication checks before page rendering
- Adding/modify request/response headers
- Performing redirects based on request conditions
- Working with cookies or authentication in the request flow
Migration Pattern
Before (Next.js 15 and earlier):
// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export function middleware(request: NextRequest) {
// Authentication check
const token = request.cookies.get('auth-token')
if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url))
}
return NextResponse.next()
}
export const config = {
matcher: ['/dashboard/:path*', '/api/:path*'],
}
After (Next.js 16 with Proxy):
// proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export async function proxy(request: NextRequest) {
// Next.js 16: All dynamic APIs are now async
// Authentication check
const cookieStore = await import('next/headers').then(m => m.cookies());
const token = cookieStore.get('auth-token');
if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url))
}
return NextResponse.next()
}
export const config = {
matcher: ['/dashboard/:path*', '/api/:path*'],
}
Complete Proxy Example with Authentication
// proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export async function proxy(request: NextRequest) {
const { pathname } = request.nextUrl
// Public routes that don't require authentication
const isPublicRoute =
pathname === '/login' ||
pathname === '/register' ||
pathname.startsWith('/api/auth')
// Protected routes that require authentication
const isProtectedRoute =
pathname.startsWith('/dashboard') ||
pathname.startsWith('/profile') ||
pathname.startsWith('/api/private')
if (isProtectedRoute && !isPublicRoute) {
// In Next.js 16, access cookies asynchronously
const cookieStore = await import('next/headers').then(m => m.cookies());
const token = cookieStore.get('auth-token')
if (!token) {
// Redirect to login page
const loginUrl = new URL('/login', request.url)
loginUrl.searchParams.set('callbackUrl', pathname)
return NextResponse.redirect(loginUrl)
}
}
// Continue with the request
return NextResponse.next()
}
export const config = {
matcher: [
/*
* Match all request paths except for the ones starting with:
* - api (API routes)
* - _next/static (static files)
* - _next/image (image optimization files)
* - favicon.ico (favicon file)
*/
'/((?!api|_next/static|_next/image|favicon.ico).*)',
],
}
Configuration Update
Before (Next.js 15):
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
skipMiddlewareUrlNormalize: true,
}
module.exports = nextConfig
After (Next.js 16):
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
skipProxyUrlNormalize: true,
}
module.exports = nextConfig
Key Differences
| Next.js 15 Middleware | Next.js 16 Proxy |
|---|---|
| Runs in Edge Runtime | Runs in Node.js Runtime |
File: middleware.ts |
File: proxy.ts |
Function: middleware() |
Function: proxy() |
Config: skipMiddlewareUrlNormalize |
Config: skipProxyUrlNormalize |
| Limited request data access | Full Node.js capabilities |
TypeScript Considerations
When using the proxy pattern in Next.js 16, keep in mind that all dynamic APIs now return promises:
// ✅ Correct in Next.js 16
export async function proxy(request: NextRequest) {
const headersList = await import('next/headers').then(m => m.headers());
const userAgent = headersList.get('user-agent');
// Modify response headers
const response = NextResponse.next();
response.headers.set('x-custom-header', 'proxy-value');
return response;
}