routing-middleware

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:

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.

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

// middleware.ts (project root)
import

Helper Methods (@vercel/functions)

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

For Next.js, equivalent helpers are on NextResponse (next(), rewrite(), redirect()) and NextRequest (request.geo, request.ip).

Matcher Configuration

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

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

Common Patterns

IP-Based Header Injection

A/B Testing via Edge Config

Background Processing

Request Limits

Three CDN Routing Mechanisms

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.

Project-Level Routes — Configuration Methods

Project-level routes take effect instantly (no deploy required). Four ways to manage them:

Use project-level routes for operational changes (CORS headers, API proxy rewrites, A/B redirects) that shouldn't require a full redeploy.

Programmatic Configuration with vercel.ts

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:

CLI commands:

• npx @vercel/config compile — compile to JSON (stdout)
• npx @vercel/config validate — validate and show summary
• npx @vercel/config generate — generate vercel.json locally for development

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

When to Use

• Geo-personalization of static pages (runs before cache)
• A/B testing rewrites with Edge 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

When NOT to Use

• Need full Node.js APIs in Next.js → use proxy.ts
• General compute at the edge → use Edge Functions
• 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)

References

• 📖 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