AGENT SKILL

routing-middleware

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.

License 许可
MIT
所属仓库
rossboyd/quickque
最近更新
2026-09-22
Stars
★ 0
Forks
0

01 前言 Front Matter

name
routing-middleware
metadata
{ "docs": [ "https://nextjs.org/docs/app/building-your-application/routing/middleware", "https://vercel.com/docs/routing-middleware" ], "sitemap": "https://nextjs.org/sitemap.xml", "priority": 6, "bashPatterns": [ "\\bnpx\\s+@vercel/config\\b" ], "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" ] }
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.

02 资源文件 1

03 SKILL.md 正文

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:

Concept File Runtime Scope When to Use
Vercel Routing Middleware middleware.ts (root) Edge/Node/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.
Edge Functions Any function file V8 isolates General-purpose Standalone edge compute endpoints, not an interception layer

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 { 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'
};

Helper Methods (@vercel/functions)

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

Helper Purpose
next() Continue middleware chain (optionally modify headers)
rewrite(url) Transparently serve content from a different URL
geolocation(request) Get city, country, latitude, longitude, region
ipAddress(request) Get client IP address
waitUntil(promise) Keep function running after response is sent

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:

// 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).

Common Patterns

IP-Based Header Injection

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

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

A/B Testing via Edge Config

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

export default async function middleware(request: Request) {
  const variant = await get('experiment-homepage'); // <1ms read
  const url = new URL(request.url);
  url.pathname = variant === 'B' ? '/home-b' : '/home-a';
  return rewrite(url);
}

Background Processing

import type { RequestContext } from '@vercel/functions';

export default function middleware(request: Request, context: RequestContext) {
  context.waitUntil(
    fetch('https://analytics.example.com/log', { method: 'POST', body: request.url })
  );
  return new Response('OK');
}

Request Limits

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.

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:

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

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

04 同仓库更多 Skills

rossboyd
rossboyd/quickque

skill-installer

Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).

★ 0
rossboyd
rossboyd/quickque

skill-creator

Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.

★ 0
rossboyd
rossboyd/quickque

review-agent

Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.

★ 0
rossboyd
rossboyd/quickque

plugin-creator

Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.

★ 0
rossboyd
rossboyd/quickque

openai-docs

Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.

★ 0
rossboyd
rossboyd/quickque

imagegen

Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.

★ 0