Next.js Middleware to Proxy: How to Migrate middleware.ts to proxy.ts in Next.js 16

In Next.js 16, the middleware.ts file has been deprecated and renamed to proxy.ts. While existing middleware still runs, every build now prints a deprecation warning. This guide outlines the migration process step by step, with warnings and errors observed from Next.js 16.4.5 on a small test app.

Middleware vs proxy:

The behavior remains the same feature under a new name. The exported function name changes from middleware to proxy, and Proxy always runs on the Node.js runtime.

Step 1: Deprecation warning

After implementing auth-redirect middleware in Next.js 16.4.5, the codemod generated a deprecation warning:

⚠ The middleware file convention is deprecated. Please use proxy instead.

Step 2: Run the codemod

Running npx @next/codemod@canary middleware-to-proxy automatically renamed middleware.ts to proxy.ts and changed the exported function from middleware to proxy. No other changes were made, and the build ran without deprecation warnings. Subsequently, tests confirm that the redirected URL includes the session cookie and that the x-user header is set correctly.

Step 3: Manual migration (if codemod not possible)

Two edits are required: rename middleware.ts to proxy.ts and rename the exported function to proxy (or use a default export). If pageExtensions was customized, the filename should follow the new convention.

Potential migration errors:

- Both middleware and proxy files are detected: delete the old middleware.ts file.

- Proxy does not support Edge runtime: remove runtime from the config or switch to the experimental-edge value.

After migration, matchers remain unchanged, execution order stays the same, and skipMiddlewareUrlNormalize is now skipProxyUrlNormalize. Testing helpers have been updated, with unstable_doesProxyMatch replacing unstable_doesMiddlewareMatch. Proxy should not be used as the sole authentication check.