routing-middleware

name	routing-middleware
description	Vercel Routing Middleware guidance — request interception before cache, rewrites, redirects, personalization. Works with any framework. Supports Edge, Node.js, and Bun runtimes. Use when intercepting requests at the platform level.
metadata	{"priority":6,"docs":["https://nextjs.org/docs/app/building-your-application/routing/middleware","https://vercel.com/docs/routing-middleware"],"sitemap":"https://nextjs.org/sitemap.xml","pathPatterns":["middleware.ts","middleware.js","middleware.mts","middleware.mjs","proxy.ts","proxy.js","proxy.mts","proxy.mjs","src/middleware.ts","src/middleware.js","src/middleware.mts","src/middleware.mjs","src/proxy.ts","src/proxy.js","src/proxy.mts","src/proxy.mjs","vercel.json","apps/*/vercel.json","vercel.ts","vercel.mts"],"bashPatterns":["\\bnpx\\s+@vercel/config\\b"]}
validate	[{"pattern":"NextResponse.*from\\s+['\"]next/server['\"]|from\\s+['\"]next/server['\"].*NextResponse","message":"Next.js middleware.ts is renamed to proxy.ts in Next.js 16 — rename the file and use the Node.js runtime. Run Skill(nextjs) for proxy.ts migration guidance.","severity":"recommended","upgradeToSkill":"nextjs","upgradeWhy":"Guides migration from middleware.ts to proxy.ts with correct file placement, Node.js runtime, and Next.js 16 patterns.","skipIfFileContains":"proxy\\.ts|runtime.*nodejs"}]
retrieval	{"aliases":["request interceptor","middleware","rewrite rules","redirect rules"],"intents":["intercept requests","add middleware","configure rewrites","set up redirects"],"entities":["middleware","rewrite","redirect","personalization","Edge"]}
chainTo	[{"pattern":"from\\s+['\"\"]next-auth['\"\"]","targetSkill":"auth","message":"Auth logic in middleware — loading Auth guidance for Clerk/Auth0 integration patterns."},{"pattern":"NextResponse.*from\\s+['\"]next/server['\"]|from\\s+['\"]next/server['\"].*NextResponse","targetSkill":"nextjs","message":"middleware.ts with next/server imports detected — loading Next.js guidance for proxy.ts migration (Next.js 16 renames middleware.ts to proxy.ts with Node.js runtime).","skipIfFileContains":"proxy\\.ts|runtime.*nodejs"},{"pattern":"from\\s+['\"\"](cookie|cookies-next)['\"\"]|req\\.cookies\\.get\\s*\\(|NextResponse\\.next\\(\\s*\\{.*headers","targetSkill":"vercel-flags","message":"Cookie-based routing in middleware — loading Vercel Flags guidance for managed feature flags with Edge Config storage.","skipIfFileContains":"@vercel/flags|@vercel/edge-config"},{"pattern":"from\\s+['\"\"](jsonwebtoken)['\"\"]|jwt\\.(verify|decode)\\(","targetSkill":"auth","message":"Manual JWT verification in middleware — loading Auth guidance for managed auth middleware patterns (Clerk, Descope).","skipIfFileContains":"clerkMiddleware|@clerk/|@auth0/"}]

Vercel Routing Middleware

You are an expert in Vercel Routing Middleware — the platform-level request interception layer.

What It Is

Routing Middleware runs before the cache on every request matching its config. It is a Vercel platform feature (not framework-specific) that works with Next.js, SvelteKit, Astro, Nuxt, or any deployed framework. Built on Fluid Compute.

• File: middleware.ts or middleware.js at the project root
• Default export required (function name can be anything)
• Runtimes: Edge (default), Node.js (runtime: 'nodejs'), Bun (Node.js + bunVersion in vercel.json)

CRITICAL: Middleware Disambiguation

There are THREE "middleware" concepts in the Vercel ecosystem:

Concept	File	Runtime	Scope	When to Use
Vercel Routing Middleware	middleware.ts (root)	Edge/Node/Bun	Any framework, platform-level	Request interception before cache: rewrites, redirects, geo, A/B
Next.js 16 Proxy	proxy.ts (root, or src/proxy.ts if using --src-dir)	Node.js only	Next.js 16+ only	Network-boundary proxy needing full Node APIs. NOT for auth.
Edge Functions	Any function file	V8 isolates	General-purpose	Standalone edge compute endpoints, not an interception layer

Why the rename in Next.js 16: middleware.ts → proxy.ts clarifies it sits at the network boundary (not general-purpose middleware). Partly motivated by CVE-2025-29927 (middleware auth bypass via x-middleware-subrequest header). The exported function must also be renamed from middleware to proxy. Migration codemod: npx @next/codemod@latest middleware-to-proxy

Deprecation: Next.js 16 still accepts middleware.ts but treats it as deprecated and logs a warning. It will be removed in a future version.