/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/api-reference/file-conventions/proxy"
    - "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+[''""](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.

• **Preferred platform configuration**: Set `proxy.entrypoint` in `vercel.json`. The entrypoint can use any supported filename or directory and runs on Node.js. Frameworks that build their own routing middleware (Next.js, Astro) do not use the `proxy` property; use the framework's file convention instead.
• **File convention**: `middleware.ts` or `middleware.js` at the project root. This convention defaults to Edge; set `runtime: 'nodejs'` to use Node.js.
• **Next.js 16**: Use `proxy.ts` and export `proxy`. Next.js Proxy runs on Node.js only.

CRITICAL: Middleware Disambiguation

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

| Concept | File | Runtime | Scope | When to Use | |---------|------|---------|-------|-------------| | **Vercel Routing Middleware** | `proxy.entrypoint` or `middleware.ts` | Node/Edge/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. | | **Vercel Functions** | Route or function file | Node/Bun/Python/Rust | General-purpose | Request handlers and backend compute, not an interception layer |

**Why the rename in Next.js 16** (`middleware.ts` → `proxy.ts`): "middleware" was often confused with Express.js middleware, and Next.js recommends the feature only as a last resort while it builds better APIs; "proxy" says what it is, a network boundary in front of the app. 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.

Bun Runtime

To run Routing Middleware (and all Vercel Functions) on Bun, add `bunVersion` to `vercel.json`:

{
  "bunVersion": "1.x"
}

Set the middleware runtime to `nodejs` — Bun replaces the Node.js runtime transparently:

export const config = {
  runtime: 'nodejs', // Bun swaps in when bunVersion is set
};

Bun reduces average latency by ~28% in CPU-bound workloads. Currently in Public Beta — supports Next.js, Express, Hono, and Nitro.

Basic Example

Configure an explicit entrypoint for framework-agnostic Routing Middleware:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "proxy": {
    "entrypoint": "proxy.ts",
    "matcher": ["/((?!_next/static|favicon.ico).*)"]
  }
}

// proxy.ts
import { geolocation, rewrite } from '@vercel/functions';

export default function proxy(request: Request) {
  const { country } = geolocation(request);
  const url = new URL(request.url);
  url.pathname = country === 'US' ? '/us' + url.pathname : '/intl' + url.pathname;
  return rewrite(url);
}

Helper Methods (`@vercel/functions`