routing-middleware

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

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.

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

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.

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.

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);
}

For non-Next.js frameworks, import from @vercel/functions:

For Next.js, NextResponse provides next(), rewrite(), and redirect(). Use geolocation(request) and ipAddress(request) from @vercel/functions; NextRequest.geo and NextRequest.ip were removed in Next.js 15.

Middleware runs on every route by default. Use config.matcher to scope it:

// Single path
export const config = { matcher: '/dashboard/:path*' };

// Multiple paths
export const config = { matcher: ['/dashboard/:path*', '/api/:path*'] };

// Regex: exclude static files
export const config = {
  matcher: ['/((?!_next/static|favicon.ico).*)'],
};

Tip: Using matcher is preferred — unmatched paths skip middleware invocation entirely (saves compute).

Vercel's CDN supports three routing mechanisms, evaluated in this order:

Project-level routes (added March 2026) let you update routing rules — response headers, rewrites to external APIs — without triggering a new deployment. They run after bulk redirects and before deployment config routes. Available on all plans.

Instead of static vercel.json, you can use vercel.ts (or .js, .mjs, .cjs, .mts) with the @vercel/config package for type-safe, dynamic routing configuration:

// vercel.ts
import { routes, type VercelConfig } from '@vercel/config/v1';

export const config: VercelConfig = {
  rewrites: [
    routes.rewrite('/api/(.*)', 'https://backend.example.com/$1'),
  ],
  headers: [
    routes.header('/(.*)', [{ key: 'X-Frame-Options', value: 'DENY' }]),
  ],
};

For project-level rules that take effect without a deployment, use vercel routes add, inspect staged changes with vercel routes list --diff, then run vercel routes publish.

Constraint: Only one config file per project — vercel.json or vercel.ts, not both.

• Geo-personalization of static pages (runs before cache)
• A/B testing rewrites with Global Config
• Custom redirects based on request properties
• Header injection (CSP, CORS, custom headers)
• Lightweight auth checks (defense-in-depth only — not sole auth layer)
• Project-level routes for headers/rewrites without redeploying

• Need full Node.js APIs in Next.js → use proxy.ts
• General compute or request handling → use Vercel Functions on the default Node.js runtime
• Heavy business logic or database queries → use server-side framework features
• Auth as sole protection → use Layouts, Server Components, or Route Handlers
• Thousands of static redirects → use Bulk Redirects (up to 1M per project)

• 📖 docs: https://vercel.com/docs/routing-middleware
• 📖 API reference: https://vercel.com/docs/routing-middleware/api
• 📖 getting started: https://vercel.com/docs/routing-middleware/getting-started