Middleware

Lightweight request interception running at the edge (V8 runtime). Use for redirects, rewrites, auth guards, A/B testing, and header injection.

> ⚠️ Framework projects (Next.js, Nuxt, etc.): Do NOT use this platform middleware format. Use the framework's built-in middleware instead (e.g. Next.js middleware.ts with NextRequest/NextResponse). The patterns below are for non-framework or pure static projects only.

Basic middleware

File: middleware.js (project root)

javascript
export function middleware(context) {
  const { request, next, redirect, rewrite } = context;

  // Pass through — no modification
  return next();
}

Context API

| Property | Type | Description | |----------|------|-------------| | request | Request | Current request object | | next(options?) | Function | Continue to origin; optionally modify headers | | redirect(url, status?) | Function | Redirect (default 307) | | rewrite(url) | Function | Rewrite request path (transparent to client) | | geo | GeoProperties | Client geolocation | | clientIp | string | Client IP address |

Route matching

By default middleware runs on ALL routes. Use config.matcher to limit scope:

javascript
// Only run on /api/* routes
export const config = {
  matcher: ['/api/:path*'],
};

export function middleware(context) {
  // Auth check for API routes only
  const token = context.request.headers.get('Authorization');
  if (!token) {
    return new Response('Unauthorized', { status: 401 });
  }
  return context.next();
}

Matcher patterns:

javascript
// Single path
export const config = { matcher: '/about' };

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

// Regex
export const config = { matcher: ['/api/.*', '^/user/\\d+$'] };

Common patterns

URL Redirect

javascript
export function middleware(context) {
  const url = new URL(context.request.url);

  if (url.pathname === '/old-page') {
    return context.redirect('/new-page', 301);
  }
  return context.next();
}

URL Rewrite (transparent proxy)

javascript
export function middleware(context) {
  const url = new URL(context.request.url);

  if (url.pathname.startsWith('/blog')) {
    return context.rewrite('/content' + url.pathname);
  }
  return context.next();
}

Add request headers

javascript
export function middleware(context) {
  return context.next({
    headers: {
      'x-request-id': crypto.randomUUID(),
      'x-client-ip': context.clientIp,
      'x-country': context.geo.countryCodeAlpha2,
    },
  });
}

Auth guard

javascript
export const config = {
  matcher: ['/api/:path*', '/admin/:path*'],
};

export function middleware(context) {
  const token = context.request.headers.get('Authorization');
  if (!token || !token.startsWith('Bearer ')) {
    return new Response(JSON.stringify({ error: 'Unauthorized' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' },
    });
  }
  return context.next();
}

Geo-based routing

javascript
export function middleware(context) {
  const country = context.geo.countryCodeAlpha2;

  if (country === 'CN') {
    return context.rewrite('/zh' + new URL(context.request.url).pathname);
  }
  return context.next();
}

A/B Testing

javascript
export function middleware(context) {
  const url = new URL(context.request.url);

  if (url.pathname === '/landing') {
    const variant = Math.random() < 0.5 ? '/landing-a' : '/landing-b';
    return context.rewrite(variant);
  }
  return context.next();
}

Direct JSON response

javascript
export function middleware(context) {
  const url = new URL(context.request.url);

  if (url.pathname === '/api/health') {
    return new Response(JSON.stringify({ status: 'ok', timestamp: Date.now() }), {
      headers: { 'Content-Type': 'application/json' },
    });
  }
  return context.next();
}

GeoProperties

Available on context.geo:

| Property | Type | Example | |----------|------|---------| | countryName | string | Singapore | | countryCodeAlpha2 | string | SG | | countryCodeAlpha3 | string | SGP | | regionName | string | — | | cityName | string | Singapore | | latitude | number | 1.29027 | | longitude | number | 103.851959 | | asn | number | 132203 |