Why Next.js 16 Replaced middleware.ts with proxy.ts

Today I started a new Next.js project, but something unexpected happened.

None of my protected routes were behaving as expected.

The terminal displayed a warning:

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

At first, I thought something was wrong with my project.

Instead, I had just encountered a change introduced in Next.js 16.

Why the Change?

Reading the official migration guide revealed the reason.

The name middleware often caused confusion because many developers associated it with Express.js middleware.

Although Next.js middleware serves a different purpose, the similar naming led to incorrect expectations.

To make its intent clearer, the Next.js team renamed the file convention to proxy.ts.

The framework provides two ways to migrate.

The first is to use the official codemod:

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

The second is even simpler for smaller projects:

After doing that, the project works with the new convention.

While fixing the warning, I started wondering:

How did Next.js know to show this message on my computer?

Initially, I assumed that every time I ran:

npm run dev

npm contacted the internet to fetch the latest framework guidelines.

That turned out to be incorrect.

The explanation is much simpler.

When we install Next.js, the framework's code is downloaded into the project's node_modules directory.

Running npm run dev simply executes that locally installed version.

The deprecation warning is already part of the Next.js 16 source code—it isn't fetched from the internet each time the project starts.

This also explains why a Next.js project can run perfectly well without an internet connection after dependencies have been installed.

Today's lesson wasn't just about renaming a file.

It reminded me to understand how the tools I use actually work.

Frameworks evolve, conventions change, and sometimes a simple warning message becomes an opportunity to learn something about the ecosystem itself.

As I continue building projects, I'm documenting not only what I build but also the small lessons I learn along the way.