- Next.js middleware runs before every matched request reaches your route handler. It's the right place for redirects, rewrites, and header modifications. - In Next.js 16, `middleware.ts` was renamed to `proxy.ts` and the exported function was renamed from `middleware` to `proxy`. Functionality is identical. `proxy.ts` runs on Node.js by default. If you need Edge runtime, keep using `middleware.ts` for now. it still works but shows a deprecation warning. - The most common use cases: auth redirects, locale detection, A/B testing, security headers, and rate limiting. - Middleware is NOT a security boundary. Auth bypass vulnerabilities have proven this multiple times. Always verify auth in Server Actions and Route Handlers too. - The `matcher` config is how you control which routes middleware runs on. Get it wrong and it runs on everything including static files. - Migrate from middleware.ts to proxy.ts by running `npx @next/codemod@canary middleware-to-proxy`.

## What Is Next.js Middleware? Next.js middleware is code that runs before a request reaches your route handler, page, or API endpoint. It intercepts incoming requests, inspects them, and decides what to do: pass them through, redirect, rewrite, or respond directly. Think of it as a gatekeeper. Every request matching your config hits middleware first. That gives you a place to handle cross-cutting concerns in a single file rather than scattering logic across every route. Authentication checks, locale detection, A/B routing, security headers. one file, everything covered. In [Next.js](https://nextjs.org) 16, middleware was officially renamed to **proxy** to better reflect what it actually does. The nextjs proxy now lives in `proxy.ts` instead of `middleware.ts`, and the exported function is `proxy` instead of `middleware`. Functionality is identical. If you're still on Next.js 15 or earlier, everything in this guide applies. just use the old names. One thing worth knowing upfront: Next.js itself recommends using middleware as a last resort. The framework is moving toward more specific APIs. Use it when you genuinely need request interception before routing. Don't reach for it just because it's there.

## Middleware vs Proxy: What Changed in Next.js 16 This is the most important thing to know if you're upgrading. **What changed:** - `middleware.ts` is now `proxy.ts` - `export function middleware()` is now `export function proxy()` - `proxy.ts` runs on Node.js by default. Edge runtime is not supported in proxy.ts yet. use `middleware.ts` if you need Edge. - Config flags renamed: `skipMiddlewareUrlNormalize` is now `skipProxyUrlNormalize` **What did NOT change:** - The `config` export with `matcher` is identical - `NextRequest`, `NextResponse`, cookies, headers: all the same APIs - All existing patterns (auth redirects, rewrites, header modifications) work exactly the same **Why Next.js made the change:** The term "middleware" was often confused with Express.js middleware, which encouraged misuse. The name "proxy" clarifies that this feature acts as a network boundary in front of the app: intercepting requests before they reach the application layer. **The edge runtime situation (important):** The official Next.js 16 upgrade guide states: "The edge runtime is NOT supported in proxy. The proxy runtime is nodejs, and it cannot be configured. If you want to continue using the edge runtime, keep using middleware." But the Next.js 16 release notes clarify: "The middleware.ts file is still available for Edge runtime use cases, but it is deprecated and will be removed in a future version." In plain terms: `proxy.ts` runs on Node.js. If you need Edge runtime, keep using `middleware.ts` for now. it still works but shows a deprecation warning. Next.js has said they'll release further Edge runtime instructions in a future minor release. Don't panic if you need Edge. just don't move to proxy.ts yet. **Migrate with the codemod:** ```bash npx @next/codemod@canary middleware-to-proxy ``` This renames the file and updates the exported function automatically across your entire project. **Before (Next.js 15 and earlier):** ```ts // middleware.ts import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; export function middleware(request: NextRequest) { return NextResponse.next(); } export const config = { matcher: ["/dashboard/:path*"], }; ``` **After (Next.js 16):** ```ts // proxy.ts import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; export function proxy(request: NextRequest) { return NextResponse.next(); } export const config = { matcher: ["/dashboard/:path*"], }; ``` That's the entire change. The logic inside is identical.

## The Matcher Config: How to Control Where Middleware Runs The `matcher` in the `config` export is how you tell Next.js which routes to run middleware on. Get this wrong and middleware runs on every request including static files, images, and Next.js internals: which slows down your app unnecessarily. **Basic matcher:** ```ts export const config = { matcher: ["/dashboard/:path*"], }; ``` This runs middleware only on routes starting with `/dashboard/`. **The standard production matcher:** Most production Next.js apps use this pattern to exclude static files and Next.js internal routes: ```ts export const config = { matcher: [ /* * Match all request paths EXCEPT: * - _next/static (static files) * - _next/image (image optimization) * - favicon.ico * - public folder files (images, fonts, etc.) */ "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)", ], }; ``` **Matching specific routes:** ```ts export const config = { matcher: [ "/dashboard/:path*", // all dashboard routes "/api/:path*", // all API routes "/admin/:path*", // all admin routes ], }; ``` **Using negative lookahead to exclude routes:** ```ts export const config = { matcher: [ // Everything except the auth pages and public assets "/((?!sign-in|sign-up|_next|favicon.ico).*)", ], }; ``` The matcher supports regular expressions. If you're unsure whether your pattern is correct, test it against your routes before deploying.

## 1. Authentication Redirects **The most common use of Next.js middleware is redirecting unauthenticated users away from protected routes.** Check for a session token in cookies and redirect to the sign-in page if it's missing. Simple. Fast. Works in both middleware.ts and the new nextjs proxy file. ```ts // proxy.ts (Next.js 16): middleware.ts in Next.js 15 import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; export function proxy(request: NextRequest) { const { pathname } = request.nextUrl; // Check for session token const token = request.cookies.get("session-token")?.value; // If no token and trying to access protected route, redirect if (!token && pathname.startsWith("/dashboard")) { return NextResponse.redirect(new URL("/sign-in", request.url)); } // If authenticated and trying to access auth pages, redirect to dashboard if (token && (pathname === "/sign-in" || pathname === "/sign-up")) { return NextResponse.redirect(new URL("/dashboard", request.url)); } return NextResponse.next(); } export const config = { matcher: ["/((?!_next|favicon.ico|api/auth).*)" ], }; ``` **Critical warning:** proxy.ts is not a security boundary. Auth bypass vulnerabilities have been demonstrated through crafted request parameters that make the proxy see one path while the handler renders another. Always verify authentication in your Server Components, Server Actions, and Route Handlers as well. Middleware redirects are UX: not security. ```ts // app/dashboard/page.tsx: ALWAYS verify auth here too import { createClient } from "@/lib/supabase-server"; import { redirect } from "next/navigation"; export default async function DashboardPage() { const supabase = await createClient(); const { data: { user } } = await supabase.auth.getUser(); if (!user) redirect("/sign-in"); // This is your real security check return ; } ```

## 2. Redirects and Rewrites Middleware is the right place for redirect and rewrite logic that needs to run before routing: legacy URL migrations, trailing slash normalization, domain redirects. **Redirect old URLs to new ones:** ```ts // proxy.ts import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; const REDIRECTS: Record = { "/old-blog": "/blog", "/old-pricing": "/pricing", "/old-about": "/about", }; export function proxy(request: NextRequest) { const { pathname } = request.nextUrl; if (REDIRECTS[pathname]) { return NextResponse.redirect( new URL(REDIRECTS[pathname], request.url), { status: 301 } ); } return NextResponse.next(); } ``` **Rewrite requests (change the URL without redirecting the browser):** ```ts // proxy.ts: serve /blog/[slug] from /posts/[slug] without changing the URL export function proxy(request: NextRequest) { const { pathname } = request.nextUrl; if (pathname.startsWith("/blog/")) { const url = request.nextUrl.clone(); url.pathname = pathname.replace("/blog/", "/posts/"); return NextResponse.rewrite(url); } return NextResponse.next(); } ``` **Domain-based routing (serve different content based on the host):** ```ts export function proxy(request: NextRequest) { const host = request.headers.get("host"); const url = request.nextUrl.clone(); if (host === "app.yourdomain.com") { url.pathname = `/app${url.pathname}`; return NextResponse.rewrite(url); } return NextResponse.next(); } ```

## 3. Security Headers **Adding security headers in Next.js middleware is more reliable than adding them per-route.** Middleware runs before the route handler and can't be accidentally skipped. One file. Every response covered. Q&A formatted content with clear definitions is 40% more likely to be cited by AI systems. which is why the headers below each include an explanation of what they do, not just the code. ```ts // proxy.ts import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; export function proxy(request: NextRequest) { const response = NextResponse.next(); // Prevents your page from being embedded in an iframe (clickjacking protection) response.headers.set("X-Frame-Options", "DENY"); // Stops browsers from guessing content type (MIME sniffing attacks) response.headers.set("X-Content-Type-Options", "nosniff"); // Enables built-in XSS filter in older browsers response.headers.set("X-XSS-Protection", "1; mode=block"); // Forces HTTPS for 1 year including subdomains response.headers.set( "Strict-Transport-Security", "max-age=31536000; includeSubDomains" ); // Controls how much referrer info is sent with requests response.headers.set("Referrer-Policy", "strict-origin-when-cross-origin"); // Restricts which resources can load (tighten for production) response.headers.set( "Content-Security-Policy", "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline';" ); return response; } export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"], }; ``` Note: `Content-Security-Policy` with `'unsafe-eval'` and `'unsafe-inline'` is permissive: tighten it for your specific use case once you know which scripts and styles you're loading.

## 4. Locale Detection and Internationalization Middleware is the standard place to detect a user's preferred locale and redirect them to the appropriate URL prefix. ```ts // proxy.ts import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; const SUPPORTED_LOCALES = ["en", "fr", "de", "es"]; const DEFAULT_LOCALE = "en"; function getLocale(request: NextRequest): string { // Check cookie first (user preference) const cookieLocale = request.cookies.get("locale")?.value; if (cookieLocale && SUPPORTED_LOCALES.includes(cookieLocale)) { return cookieLocale; } // Fall back to Accept-Language header const acceptLanguage = request.headers.get("accept-language") || ""; const preferred = acceptLanguage .split(",") .map((lang) => lang.split(";")[0].trim().slice(0, 2)) .find((lang) => SUPPORTED_LOCALES.includes(lang)); return preferred || DEFAULT_LOCALE; } export function proxy(request: NextRequest) { const { pathname } = request.nextUrl; // Skip if already has a locale prefix const hasLocale = SUPPORTED_LOCALES.some( (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}` ); if (!hasLocale) { const locale = getLocale(request); return NextResponse.redirect( new URL(`/${locale}${pathname}`, request.url) ); } return NextResponse.next(); } export const config = { matcher: ["/((?!_next|api|favicon.ico).*)"], }; ``` If you're using `next-intl` for i18n, note that upgrading to Next.js 16 requires renaming `middleware.ts` to `proxy.ts`: this is a breaking change that silently breaks locale routing without an obvious error message.

## 5. A/B Testing and Feature Flags Middleware can split traffic between two versions of a page by setting a cookie and rewriting the URL: without the user seeing the URL change. ```ts // proxy.ts import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; export function proxy(request: NextRequest) { const { pathname } = request.nextUrl; // Only run A/B test on the pricing page if (pathname === "/pricing") { // Check if user already has a bucket assignment const bucket = request.cookies.get("ab-pricing-test")?.value; if (!bucket) { // Randomly assign to A or B const newBucket = Math.random() < 0.5 ? "control" : "variant"; const url = request.nextUrl.clone(); // Rewrite to the variant route if (newBucket === "variant") { url.pathname = "/pricing-v2"; } const response = NextResponse.rewrite(url); // Set the bucket cookie so the user stays in the same group response.cookies.set("ab-pricing-test", newBucket, { maxAge: 60 * 60 * 24 * 7, // 7 days httpOnly: true, sameSite: "lax", }); return response; } // Return existing bucket assignment if (bucket === "variant") { const url = request.nextUrl.clone(); url.pathname = "/pricing-v2"; return NextResponse.rewrite(url); } } return NextResponse.next(); } ```

## 6. Rate Limiting Middleware is a good place to implement rate limiting on API routes because it runs before the route handler and can reject requests early without executing any business logic. ```ts // proxy.ts: using Upstash Redis for edge-compatible rate limiting import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; import { Ratelimit } from "@upstash/ratelimit"; import { Redis } from "@upstash/redis"; const ratelimit = new Ratelimit({ redis: Redis.fromEnv(), limiter: Ratelimit.slidingWindow(10, "10 s"), // 10 requests per 10 seconds analytics: true, }); export async function proxy(request: NextRequest) { const { pathname } = request.nextUrl; // Only rate limit API routes if (pathname.startsWith("/api/")) { const ip = request.headers.get("x-forwarded-for")?.split(",")[0] || request.headers.get("x-real-ip") || "127.0.0.1"; const { success, limit, remaining, reset } = await ratelimit.limit(ip); if (!success) { return new NextResponse("Too many requests", { status: 429, headers: { "X-RateLimit-Limit": limit.toString(), "X-RateLimit-Remaining": remaining.toString(), "X-RateLimit-Reset": new Date(reset).toISOString(), "Retry-After": Math.ceil((reset - Date.now()) / 1000).toString(), }, }); } } return NextResponse.next(); } export const config = { matcher: ["/api/:path*"], }; ``` Upstash Redis is the standard choice for rate limiting in Next.js middleware because it's HTTP-based and works in any runtime. Standard Redis clients that use TCP connections don't work in the middleware runtime.

## What Not to Do in Next.js Middleware Middleware runs on every matched request. Every single one. That means bad middleware doesn't just slow down one page. it slows down your entire app. Keep it fast, keep it light, and keep business logic out of it. **Never do database queries in middleware:** ```ts // Bad: database calls in middleware add latency to every request export async function proxy(request: NextRequest) { const userId = request.cookies.get("user-id")?.value; const user = await db.users.findUnique({ where: { id: userId } }); // DON'T DO THIS if (!user.isActive) return NextResponse.redirect("/suspended"); return NextResponse.next(); } ``` Check session tokens and basic cookie values in middleware. Do database verification in Server Components or Server Actions. **Never put heavy business logic in middleware:** Middleware runs before every request. Complex computations, external API calls, file system operations: these belong in route handlers, not in the middleware layer. **Never rely on middleware as your only auth check:** As covered in the auth section, middleware can be bypassed. Treat it as a UX layer for redirects: not as a security gate. Always verify authentication in the layer that actually renders the data. **Watch out for infinite redirect loops:** If your middleware redirects `/sign-in` to `/sign-in`, you'll get an infinite loop. Always exclude auth pages from your matcher or add an explicit check. ```ts // Bad: infinite loop if the user is unauthenticated and lands on /sign-in export function proxy(request: NextRequest) { const token = request.cookies.get("session")?.value; if (!token) { return NextResponse.redirect(new URL("/sign-in", request.url)); } return NextResponse.next(); } // Good: exclude auth pages from the check export function proxy(request: NextRequest) { const { pathname } = request.nextUrl; const token = request.cookies.get("session")?.value; if (!token && !pathname.startsWith("/sign-in") && !pathname.startsWith("/sign-up")) { return NextResponse.redirect(new URL("/sign-in", request.url)); } return NextResponse.next(); } ```

## Migrating from middleware.ts to proxy.ts If you're upgrading to Next.js 16, run the [official codemod](https://nextjs.org/docs/messages/middleware-to-proxy) first: ```bash npx @next/codemod@canary middleware-to-proxy ``` This handles the file rename and function rename automatically. After running it, check for: **1. Edge runtime usage** If your Next.js middleware used `export const runtime = "edge"`, that config is not supported in proxy.ts. The proxy runs on Node.js. But you're not stuck: `middleware.ts` is still available specifically for Edge runtime use cases, just deprecated. Keep using it until Next.js ships Edge support for proxy.ts in an upcoming release. Don't force a migration if Edge is critical to your setup. **2. Config flag renames** `skipMiddlewareUrlNormalize` is now `skipProxyUrlNormalize` in `next.config.ts`. The codemod handles this too, but verify your config file after running it. **3. Third-party integrations** Libraries like `next-intl`, `next-auth`, `Clerk`, and any other library that wraps middleware need to be updated to work with proxy.ts. Check each library's changelog for Next.js 16 compatibility notes before upgrading. **4. Deprecation warnings** Next.js 16 still accepts middleware.ts but logs a deprecation warning. If you see `The middleware file convention is deprecated`, the codemod didn't run or missed a file. Check for middleware.ts in both `src/` and the root directory.

## Wrap Up Next.js middleware (now called proxy in Next.js 16) is one of the most useful and most misused features in the framework. Used correctly: for redirects, rewrites, header modifications, and lightweight request inspection: it makes cross-cutting concerns clean and centralized. Used incorrectly: for database calls, heavy business logic, or as a sole auth gate: it adds latency and creates security gaps. The rename from middleware to proxy in Next.js 16 is worth paying attention to. Not for the name change itself, but for what it signals: this is a network boundary feature, not a general-purpose backend layer. Keep it fast. Keep it light. Put your real security checks in the layer that touches your data. If you're building a Next.js product and want your project management, deployment tracking, and analytics in one workspace, check out [AdeptDev](https://adeptdev.io). Free for 7 days.

## What is Next.js middleware? Next.js middleware is code that runs before a request reaches your route handler, page, or API endpoint. It intercepts incoming requests and can redirect, rewrite, modify headers, or respond directly. It's the right place for cross-cutting concerns like auth redirects, locale detection, security headers, and rate limiting. In Next.js 16, middleware was renamed to proxy: the file is now proxy.ts and the exported function is now proxy instead of middleware. ## What changed with Next.js middleware in Next.js 16? In Next.js 16, middleware.ts was renamed to proxy.ts and the exported function was renamed from middleware to proxy. The functionality is identical. The config export with matcher stays the same. The main breaking changes are: the file name and function name, edge runtime is no longer supported in proxy.ts (it now runs on Node.js), and config flags like skipMiddlewareUrlNormalize were renamed to skipProxyUrlNormalize. Run npx @next/codemod@canary middleware-to-proxy to migrate automatically. ## How do I use Next.js middleware for authentication? Check for a session token in request cookies and redirect unauthenticated users to your sign-in page. Return NextResponse.redirect() for unauthenticated requests and NextResponse.next() to pass the request through. Use the matcher config to run auth checks only on protected routes. Critical: middleware is not a security boundary. Always verify authentication in your Server Components and Server Actions too: middleware redirects can be bypassed. ## What is the Next.js middleware matcher? The matcher in the config export controls which routes middleware runs on. Without it, middleware runs on every request including static files and Next.js internals. The standard production matcher excludes _next/static, _next/image, favicon.ico, and public assets. Matchers support regular expressions and can include multiple route patterns. The matcher config is identical in proxy.ts (Next.js 16) and middleware.ts (Next.js 15 and earlier). ## Can I use middleware for rate limiting in Next.js? Yes. Middleware is a good place to rate limit API routes because it runs before the route handler and can reject requests early without executing business logic. Use Upstash Redis for rate limiting: it's HTTP-based and works in the Node.js proxy runtime. Standard TCP-based Redis clients don't work in middleware. Implement a sliding window rate limiter and return a 429 response with appropriate headers when the limit is exceeded. ## What should I not put in Next.js middleware? Avoid database queries, external API calls, and heavy business logic in middleware: it runs on every matched request and adds latency to every page load. Never rely on middleware as your only authentication check: it can be bypassed. Never put file system operations or long-running computations in middleware. Keep middleware fast and lightweight: cookie checks, header inspection, URL manipulation, and simple redirects are the right use cases. ## How do I migrate from middleware.ts to proxy.ts in Next.js 16? Run the official codemod: npx @next/codemod@canary middleware-to-proxy. It renames the file from middleware.ts to proxy.ts and renames the exported function from middleware to proxy automatically across your project. After running it, check for edge runtime usage (no longer supported in proxy.ts), verify third-party libraries like next-intl and Clerk have Next.js 16 compatible versions, and confirm your next.config.ts config flags were updated if you used skipMiddlewareUrlNormalize.