Routing MiddlewareSkip to content
Docs
 

Routing Middleware

Routing Middleware is available on all plans

Routing Middleware executes code before a request is processed on a site, and are built on top of fluid compute. Based on the request, you can modify the response.

Because it runs globally before the cache, Routing Middleware is an effective way of providing personalization to statically generated content. Depending on the incoming request, you can execute custom logic, rewrite, redirect, add headers and more, before returning a response.

Routing Middleware configured with the proxy property runs on the Node.js runtime. With the middleware.ts file convention, the default is Edge. See runtime options for information on how to change the runtime of your Routing Middleware.

Next.js 16 users: Next.js 16 renamed the middleware file from middleware.ts to proxy.ts and changed the function export from middleware to proxy. When using Next.js 16 or later, use proxy.ts instead of middleware.ts. The proxy function runs on Node.js only (Edge runtime is not supported). See the Next.js proxy documentation for details.

Creating a Routing Middleware

You can use Routing Middleware with any framework. To add a Routing Middleware to your app, point the proxy property in vercel.json at your entrypoint:

vercel.json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "proxy": {
    "entrypoint": "proxy.ts"
  }
}

Your entrypoint exports the handler as a default export:

proxy.ts
export default function proxy(request: Request) {
  const url = new URL(request.url);
 
  // Redirect old paths
  if (url.pathname === '/old-page') {
    return new Response(null, {
      status: 302,
      headers: { Location: '/new-page' },
    });
  }
 
  // Continue to next handler
  return new Response('Hello from your Middleware!');
}
proxy.js
export default function proxy(request) {
  const url = new URL(request.url);
 
  // Redirect old paths
  if (url.pathname === '/old-page') {
    return new Response(null, {
      status: 302,
      headers: { Location: '/new-page' },
    });
  }
 
  // Continue to next handler
  return new Response('Hello from your Middleware!');
}

The entrypoint can live in a subdirectory, such as src/proxy.ts. Add proxy.matcher to limit which paths run your Routing Middleware.

You can't use proxy with frameworks that build their own routing middleware, such as Next.js and Astro. In Next.js 16 and later, add a proxy.ts file at your project root instead. See the Next.js proxy documentation for details.

Using the file convention

You can also create a middleware.ts file at your project's root directory and skip vercel.json:

middleware.ts
export default function middleware(request: Request) {
  return new Response('Hello from your Middleware!');
}
 
export const config = {
  runtime: 'nodejs',
};
middleware.js
export default function middleware(request) {
  return new Response('Hello from your Middleware!');
}
 
export const config = {
  runtime: 'nodejs',
};

The middleware.ts file should be at the same level as your app or pages directory (even if you're using a src directory). See the Quickstart guide for more information.

Logging

Routing Middleware has full support for the console API, including time, debug, timeEnd. Logs will appear inside your Vercel project by clicking View Functions Logs next to the deployment.

Using a database with Routing Middleware

If your Routing Middleware depends on a database far away from one of our supported regions, the overall latency of API requests could be slower than expected, due to network latency while connecting to the database from an edge region. To avoid this issue, use a global database. Vercel has multiple global storage products, including Global Config and Vercel Blob. You can also explore the storage category of the Vercel Marketplace to learn which option is best for you.

Limits on requests

The following limits apply to requests processed by Routing Middleware:

Runtime options

Routing Middleware is available on the Node.js, Bun, and Edge runtimes. An entrypoint set through the proxy property runs on Node.js.

With the middleware.ts file convention, the default runtime is Edge. You can change the runtime to Node.js by exporting a config object with a runtime property in your middleware.ts file.

Next.js 16 and later run the proxy on Node.js only. The Edge runtime is not available for Next.js proxy files. See the Next.js proxy documentation for details.

To use the Bun runtime, set bunVersion in your vercel.json file and your runtime config to nodejs.

middleware.ts
export const config = {
  runtime: 'nodejs', // or 'edge' (default)
};
export default function middleware(request: Request) {
  // Your middleware logic here
  return new Response('Hello from your Middleware!');
}
middleware.js
export const config = {
  runtime: 'nodejs' // or 'edge' (default)
}
export default function middleware(request: Request) {
  // Your middleware logic here
  return new Response('Hello from your Middleware!');
}

Pricing

Routing Middleware is priced using the fluid compute model, which means you are charged by the amount of compute resources used by your Routing Middleware. See the fluid compute pricing documentation for more information.

Observability

The Vercel Observability dashboard provides visibility into your routing middleware usage, including invocation counts and performance metrics. You can get more insights with Observability Plus:

  • Analyze invocations by request path
  • Break down actions by type, such as redirects or rewrites
  • View rewrite targets and frequency
  • Use the query builder for custom insights

More resources

Learn more about Routing Middleware by exploring the following resources:

Last updated August 14, 2026
Previous
Fluid Compute
Next
Getting Started

Was this helpful?

supported.