mcpField
N
nextjs-16-proxy

nextjs-16-proxy

github.com/blink-newDevelopment56 installs
Repository

About nextjs-16-proxy

A reference skill for migrating Next.js middleware to the Next.js 16 `proxy` convention and handling request rewrites before routing. It is for developers maintaining Next.js applications.

Key features

  1. 01Explains `middleware.ts` to `proxy.ts` changes
  2. 02Shows the required file location
  3. 03Describes proxy-based rewrites before routing
  4. 04Provides a middleware migration command

Use cases

  1. 01Migrating a Next.js 15 middleware file
  2. 02Rewriting paths that conflict with dynamic routes

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/blink-new/claude --skill nextjs-16-proxy

After installing, type/nextjs-16-proxyin Claude Code to confirm it loaded.

Details

From the project README

Next.js 16 Proxy Convention

Next.js 16 renamed middleware to proxy to better reflect its network boundary purpose.

Key Changes from Middleware

Old (Next.js 15)New (Next.js 16+)
middleware.tsproxy.ts
export function middleware()export function proxy()
Same locationSame location

File Location

Place proxy.ts at the same level as app or pages:

src/
├── proxy.ts      ← Correct location
├── app/
│   └── ...

NOT inside app/:

src/
├── app/
│   ├── proxy.ts  ← Wrong location
│   └── ...

Basic Template

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Example: rewrite /uploads/* to /api/uploads/*
  if (pathname.startsWith("/uploads/")) {
    const newUrl = request.nextUrl.clone();
    newUrl.pathname = pathname.replace("/uploads/", "/api/uploads/");
    return NextResponse.rewrite(newUrl);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/uploads/:path*"],
};

Common Issue: Dynamic Routes Catching Paths

When you have a dynamic route like [teamSlug] at the root, it can catch paths before rewrites in next.config.ts are applied.

Problem:

  • Request: /uploads/image.png
  • Dynamic route [teamSlug] catches it as teamSlug = "uploads"
  • Results in 404

Solution: Use proxy.ts instead of next.config.ts rewrites. Proxy runs before routing.

Migration Command

npx @next/codemod@canary middleware-to-proxy .

This automatically:

  • Renames middleware.ts → proxy.ts
  • Updates function name middleware → proxy

Comments

Markdown supported