nextjs-middleware

CoderMariusz's avatarfrom CoderMariusz

When you need to run code before a request completes: auth checks, redirects, headers, A/B testing. **Version Context**: Next.js 16.0+ uses `proxy.ts` (replaces `middleware.ts` from v15 and earlier).

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026
[Architecture Design]

When & Why to Use This Skill

This Claude skill provides comprehensive guidance and code patterns for implementing request-layer logic in Next.js applications. It specializes in the transition from legacy middleware.ts (v15) to the modern proxy.ts (v16+), helping developers handle authentication, security headers, and dynamic routing at the edge with optimized performance and best practices.

Use Cases

  • Authentication & Authorization: Implementing global guards to redirect unauthenticated users away from sensitive routes like /dashboard or /api.
  • Security Header Management: Programmatically injecting essential security headers such as X-Frame-Options and Content-Security-Policy to harden the application.
  • Version Migration: Facilitating the upgrade from Next.js 15 to 16+ by converting middleware.ts logic into the new proxy.ts standard using recommended patterns and codemods.
  • Advanced Request Matching: Configuring complex matcher patterns to exclude static assets or target specific API paths based on headers, cookies, or locales.
  • A/B Testing & Edge Routing: Executing lightweight logic before request completion to handle redirects or rewrites for experimental feature flags.
namenextjs-middleware
descriptionWhen you need to run code before a request completes: auth checks, redirects, headers, A/B testing. **Version Context**: Next.js 16.0+ uses `proxy.ts` (replaces `middleware.ts` from v15 and earlier).
version1.1.0
tokens~550
confidencehigh
- https//nextjs.org/docs/app/building-your-application/routing/middleware
last_validated2025-12-10
next_review2025-12-24
tags[nextjs, middleware, proxy, auth, routing, frontend]

When to Use

When you need to run code before a request completes: auth checks, redirects, headers, A/B testing.

Version Context: Next.js 16.0+ uses proxy.ts (replaces middleware.ts from v15 and earlier).

Patterns

Basic Proxy (Next.js 16+)

// proxy.ts (root of project)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function proxy(request: NextRequest) {
  // Runs on EVERY matched route
  return NextResponse.next();
}

// Match specific routes
export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*']
};

Legacy Middleware (Next.js 15 and earlier)

// middleware.ts (root of project)
export function middleware(request: NextRequest) {
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*']
};

Migration: Run npx @next/codemod@canary middleware-to-proxy . to auto-migrate.

Auth Redirect

export function proxy(request: NextRequest) {
  const token = request.cookies.get('session');

  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

Add Headers

export function proxy(request: NextRequest) {
  const response = NextResponse.next();

  // Add security headers
  response.headers.set('X-Frame-Options', 'DENY');
  response.headers.set('X-Content-Type-Options', 'nosniff');

  return response;
}

Matcher Patterns

export const config = {
  matcher: [
    // Match all paths except static files
    '/((?!_next/static|_next/image|favicon.ico).*)',
    // Match specific paths
    '/dashboard/:path*',
    '/api/:path*',
  ]
};

Advanced Matcher with Conditions

export const config = {
  matcher: [
    {
      source: '/api/:path*',
      locale: false,
      has: [{ type: 'header', key: 'Authorization' }],
      missing: [{ type: 'cookie', key: 'session' }],
    },
  ],
};

Anti-Patterns

  • Heavy computation in proxy (runs on every request)
  • Database queries (use Edge-compatible clients only)
  • Large dependencies (bundle size matters at edge)
  • Forgetting matcher (runs on ALL routes by default)
  • Using middleware.ts in Next.js 16+ (use proxy.ts instead)

Verification Checklist

  • Matcher configured (not running on static files)
  • No heavy computation or DB calls
  • Auth redirects tested
  • Headers properly set
  • Using proxy.ts for Next.js 16+, middleware.ts for v15 and earlier