Next.js proxy.ts Explained (with Cheat Sheet)
Your team wrote middleware.ts carefully — Edge-safe imports only, jose instead of jsonwebtoken , no direct database calls — because that's what Edge middleware demanded. Then you upgraded to Next.js 16, skimmed the release notes, and moved on. Nothing broke. Which is exactly the problem: middleware.ts still runs, but it's now the deprecated way to do the one job every non-trivial app needs —…
Next.js 16 introduced a change that affected applications that previously used middleware.ts for tasks such as authentication and redirects. The framework renamed middleware.ts to proxy.ts to clarify its role as a network boundary rather than a request handler. This change was made because proxy.ts now runs exclusively on the Node.js runtime, unlike the Edge runtime previously used by middleware.ts.
By the time you read this article, you should be familiar with Next.js 16.3, the current Active LTS release. The rename did not break existing functionality in most cases, as middleware.ts continued to run unchanged. However, it caused confusion as teams started seeing both middleware.ts and proxy.ts files in their repositories, leading to potential misjudgments about what could and couldn't be done within the new proxy.ts file.
Proxy.ts operates on every request that matches its matcher, before any layout, page, or Server Component executes. It allows you to decide whether a request is allowed to reach the app and what it can carry in with it, such as headers or rewritten paths. The advantage of this new model is that proxy.ts can utilize the full range of Node.js runtime capabilities, including built-in modules, database drivers, and other npm packages, without the need for Edge-specific compatibility checks.
However, this new model comes with a trade-off: if your application required the Edge runtime's low-latency execution for specific checks, that option is no longer available for new code. For most authentication, redirect, and rewrite tasks, this trade-off is negligible, but it's essential to consider when designing your application's architecture.
To migrate from middleware.ts to proxy.ts, follow these steps:
1. Review your existing middleware.ts file and understand its functionality.
2. Use the official codemod provided by Next.js to automate the migration process, which will rename the file to proxy.ts and update any necessary configurations.
3. Update your proxy.ts file to include your authentication, header setting, and request rewriting logic.
4. Be aware that proxy.ts can now use any Node.js runtime capabilities, so you may need to adjust your code accordingly.
5. Keep in mind that proxy.ts is the recommended approach for most applications, but Edge middleware.ts is still available for those with specific Edge runtime requirements.
This change highlights the importance of understanding the framework's updates and adapting your code accordingly. By embracing the new proxy.ts model, you can take advantage of Node.js runtime capabilities while maintaining a secure and efficient boundary for your application's incoming requests.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
