If your B2B SaaS still ships middleware.ts , the Next.js 16 rename to proxy.ts is more than a filename swap. The default runtime moves to Node, Edge-only assumptions break, and a sloppy matcher can lock CSS and images behind an auth redirect. This brief is for founders and product-engineering leads planning the migration without inventing a second auth stack. Treat the proxy as an optimistic gate: cookie presence, host-based tenant hints, and cheap redirects. Keep authoritative authorization in Server Components, Route Handlers, and Server Actions. Middleware-as-sole-security was already a smell; the rename is a good moment to fix the trust model.
What actually changed
Next.js 16.0.0 deprecated the middleware file convention and renamed it to proxy . Export proxy instead of middleware , keep a single convention file, and use the official codemod ( npx @next/codemod@canary middleware-to-proxy . ), which renames both the file and the function. Proxy defaults to the Node.js runtime, and the runtime config option is not available in proxy files: setting it throws an error. That matters for SaaS: packages that once needed Edge-compatible forks (JWT helpers, crypto, some ORM adapters) may now work in proxy, but database round trips on every navigation remain a product tax. Prefetches and soft navigations will amplify any slow check.
A safe SaaS migration checklist
Start with a branch that only renames and re-exports. Confirm production and preview both load static assets. Audit config.matcher : exclude _next/static , _next/image , favicon, and public marketing paths you intentionally leave open. Log redirect reasons with a correlation id so support can explain “why am I bouncing to login.” Next, strip any “set trusted tenant id from an unverified header” patterns. The proxy may set internal headers after verifying a session cookie or bearer token — never trust inbound tenant headers from the client. Header injection bugs are easy to misread as flaky row-level security, which is why we cover tenant boundaries in our multi-tenant isolation mistakes post.
// Illustrative proxy sketch — optimistic session gate only
import { NextRequest, NextResponse } from 'next/server';
export function proxy(request: NextRequest) {
const { pathname } = request.nextUrl;
if (pathname.startsWith('/app') && !request.cookies.get('session')) {
const url = request.nextUrl.clone();
url.pathname = '/login';
url.searchParams.set('next', pathname);
return NextResponse.redirect(url);
}
return NextResponse.next();
}
export const config = {
matcher: ['/((?!_next/static|_next/image|favicon.ico|api/public).*)'],
};Runtime and performance decisions founders should force
Ask eng to document which checks stay in proxy versus the data-access layer, and how a Node proxy affects TTFB for logged-out marketing pages versus logged-in app shells. The Next.js 16 upgrade guide is explicit: the Edge runtime is not supported in proxy, and teams that need Edge should keep using middleware for now. If you take that path, treat it as a written exception with an owner and a review date, not tribal knowledge. Also plan observability: proxy errors should appear in the same tracing product as Route Handler failures. Silent 500s at the gate look like “site down” to buyers running a procurement demo.
When not to over-engineer
Do not rebuild your entire auth provider because of a rename (if you are weighing that anyway, read our build vs buy auth guide first). Do not move entitlement checks into proxy “because Node can now query Postgres.” Do not invent custom JWT crypto in the gate when your vendor session cookie already works. The win is a clear boundary: proxy for fast optimistic routing; app layer for authorization, tenancy, and audit.
Multi-tenant header hygiene in detail
Subdomain and path-based tenancy both tempt teams to set x-tenant-id in the proxy and trust it downstream. That only works if the proxy is the sole writer after verifying the session or a signed host map. Strip inbound copies of those headers on every request. Add regression tests that send spoofed tenant headers with a valid session for tenant A and assert the app still resolves A — never B. For bearer-token API clients (mobile, partners), verify the token in the data layer even if the proxy already peeked at it for routing. Double verification is cheaper than a cross-tenant read in a security questionnaire aftermath.
Preview environments and auth cookies
Preview apps often break because cookie domains, HTTPS, and proxy matchers disagree. Document a preview auth strategy: separate cookie name, tunnel-friendly redirects, and a matcher that does not protect the preview login assets themselves. Founders should insist on a smoke test URL in every PR that proves login still works after proxy changes — otherwise you only discover breakage when a designer opens a Vercel preview.
Migration sequencing for production SaaS
Ship rename + export change behind a feature branch with canary traffic if your host allows. Watch login success rate, redirect loops, and static asset 404s for 24–48 hours. Keep a documented rollback: restore middleware file convention only if you must, knowing Next.js 16 prefers one convention. Brief support on the new redirect query params so “I can’t log in” tickets cite next= correctly. Update runbooks and architecture diagrams. “We still say middleware in Slack” becomes an onboarding tax for every new hire.
Server Functions quietly follow your matcher
The proxy docs flag a trap that matters for SaaS forms: Server Functions are not separate routes. They are handled as POST requests to the route where they are used, so a matcher that excludes a path also skips Server Function calls on that path. A matcher tweak, or a refactor that moves a Server Function to another route, can silently remove proxy coverage. The fix is the same trust model as above: verify the session and the user's role inside every Server Function, and treat proxy coverage as a bonus. Also note that even when _next/data is excluded in a negative matcher, proxy still runs for those data routes on purpose, so do not assume an exclusion turns the gate off everywhere.
Where things stand in November 2026
Next.js 16.4.5 is the current stable release on npm as of November 9, 2026, and the middleware convention is still deprecated rather than removed. That gives teams room to migrate on their own schedule, but every month on middleware.ts is another month of new hires learning the old name. If you are also planning the caching changes, pair this work with our Next.js 16.4 Cache Components plan so you only re-test auth flows once.
Security review talking points
Buyers ask whether auth is enforced only at the edge. Answer honestly: proxy is optimistic; Server Actions and Route Handlers re-check session and RBAC; RLS or equivalent enforces tenancy in the database. The proxy migration is a chance to put that sentence in your Trust Center instead of improvising on a sales engineering call.
Founder takeaway
The middleware-to-proxy migration is a trust-boundary cleanup dressed as a framework rename. Ship the rename with matcher hygiene, strip unverified tenant headers, keep authoritative auth deeper in the stack, and measure redirect latency on real app routes. Founders who treat this as “rename and hope” inherit Edge-era bugs on a Node runtime — the worst of both worlds. If you would rather hand the upgrade to a team that has done it, talk to us or see our web and SaaS services . And if the codebase needs more than a rename, our rewrite vs incremental rescue guide helps you scope it.
