𝗜 𝗠𝗲𝘀𝘀𝗲𝗱 𝗨𝗽 𝗠𝘆 𝗡𝗲𝘅𝘁.𝗷𝘀 𝗔𝘂𝘁𝗵 𝗠𝗮𝘁𝗰𝗵𝗲𝗿 𝗧𝗵𝗿𝗲𝗲 𝗧𝗶𝗺𝗲𝘀
I broke three projects before I understood how proxy.ts works in Next.js 16.
The error was silent. No logs. No warnings. No errors. Just broken redirects and security gaps.
If you are upgrading to Next.js 16, do not just run a codemod and walk away. You need to check these three things.
𝗧𝗵𝗲 𝗠𝗶𝗴𝗿𝗮𝘁𝗶𝗼𝗻 𝗧𝗿𝗮𝗽
Next.js renamed middleware.ts to proxy.ts. This is not just a name change.
- middleware.ts ran on the Edge runtime. It had limited crypto support.
- proxy.ts runs on the Node.js runtime by default. It has full crypto support.
If you manually update your package without a codemod, your old middleware.ts file might still exist. It will compile fine. It will pass TypeScript checks. But it will do nothing. Your routes will not be intercepted. Your redirects will not fire.
Check these three things manually:
- proxy.ts must exist at your project root.
- The exported function must be named proxy.
- middleware.ts must be deleted.
𝗧𝗵𝗲 𝗠𝗮𝘁𝗰𝗵𝗲𝗿 𝗚𝗮𝗽
The matcher is where auth setups fail most often.
If your matcher is too broad, the proxy runs on every CSS and image file. This causes infinite redirect loops.
If your matcher is too narrow, you create a security hole.
If a route is not in your matcher, the proxy never runs. A user can send their own headers to that route. If your Server Component trusts those headers, an attacker can impersonate anyone.
𝗧𝗵𝗲 𝗙𝗶𝘅: 𝗗𝗼𝗻’𝘁 𝗧𝗿𝘂𝘀𝘁 𝗛𝗲𝗮𝗱𝗲𝗿𝘀
I learned the hard way: do not rely solely on headers forwarded by the proxy.
Use a two-layer approach:
- The proxy acts as a fast gate at the network boundary.
- The Server Component verifies the JWT directly from the cookie at render time.
This second check closes the gap. Even if the matcher misses a route, the Server Component will catch the invalid user. It adds a few milliseconds of latency but prevents a massive security failure.
𝗦𝘂𝗺𝗺𝗮𝗿𝘆 𝗖𝗵𝗲𝗰𝗸𝗹𝗶𝘀𝘁:
- Use proxy.ts for auth.
- Use Node.js runtime for full crypto support.
- Set headers on the request, not the response.
- Always verify the JWT inside Server Components.