routing-middleware

{
 "bunVersion": "1.x"
}

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

// middleware.ts (project root)
import { geolocation, rewrite } from '@vercel/functions';

export default function middleware(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);
}

export const config = {
 runtime: 'edge', // 'edge' (default) | 'nodejs'
};

import { ipAddress, next } from '@vercel/functions';

export default function middleware(request: Request) {
 return next({ headers: { 'x-real-ip': ipAddress(request) || 'unknown' } });
}

import { get } from '@vercel/edge-config';
import { rewrite } from '@vercel/functions';

export default async function middleware(request: Request) {
 const variant = await get('experiment-homepage'); // Limit Value 
 Max URL length 14 KB 
 Max request body 4 MB 
 Max request headers 64 headers / 16 KB total

## Three CDN Routing Mechanisms

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

 Order Mechanism Scope Deploy Required How to Configure 
 1 **Bulk Redirects** Up to 1M static path→path redirects No (runtime via Dashboard/API/CLI) Dashboard, CSV upload, REST API 
 2 **Project-Level Routes** Headers, rewrites, redirects No (instant publish) Dashboard, API, CLI, Vercel SDK 
 3 **Deployment Config Routes** Full routing rules Yes (deploy) `vercel.json`, `vercel.ts`, `next.config.ts` 
 

 **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:

 Method How 
 **Dashboard** Project → CDN → Routing tab. Live map of global traffic, cache management, and route editor in one view. 
 **REST API** `GET/POST/PATCH/DELETE /v1/projects/{projectId}/routes` — 8 dedicated endpoints for CRUD on project routes. 
 **Vercel CLI** Managed via `vercel.ts` / `@vercel/config` commands (`compile`, `validate`, `generate`). 
 **Vercel SDK** `@vercel/config` helpers: `routes.redirect()`, `routes.rewrite()`, `routes.header()`, plus `has`/`missing` conditions and transforms. 
 

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

## 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](https://vercel.com/docs/routing-middleware) 

- 📖 API reference: [https://vercel.com/docs/routing-middleware/api](https://vercel.com/docs/routing-middleware/api) 

- 📖 getting started: [https://vercel.com/docs/routing-middleware/getting-started](https://vercel.com/docs/routing-middleware/getting-started)

// 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).*)'],
};

// vercel.ts
import { defineConfig } from '@vercel/config';

export default defineConfig({
 rewrites: [
 { source: '/api/:path*', destination: 'https://backend.example.com/:path*' },
 ],
 headers: [
 { source: '/(.*)', headers: [{ key: 'X-Frame-Options', value: 'DENY' }] },
 ],
});