Upgrading to Next.js 16: proxy.ts, Turbopack and async params

Next.js 16 is mostly an evolutionary upgrade, but a few changes will touch every project. This is the checklist we use.

1. middleware.ts becomes proxy.ts

middleware is renamed to proxy to make its role clearer: it sits at the network boundary in front of your app. The function is exported as proxy and runs on the Node.js runtime.

1// proxy.ts
2import { NextRequest, NextResponse } from 'next/server';
3

4export function proxy(request: NextRequest) {
5  if (!request.cookies.has('session')) {
6    return NextResponse.redirect(new URL('/login', request.url));
7  }
8  return NextResponse.next();
9}
10

11export const config = {
12  matcher: ['/dashboard/:path*'],
13};

Keep it small. Authorization for real data must still happen close to the data, not only in the proxy.

2. Turbopack is the default bundler

next dev and next build use Turbopack. Vendor claims are 2x to 5x faster builds and much faster Fast Refresh, but measure your own project. If a custom webpack setup blocks you, opt out explicitly:

1next build --webpack

3. Request APIs are async

params, searchParams, cookies() and headers() are asynchronous. Await them.

1export default async function Page({
2  params,
3  searchParams,
4}: {
5  params: Promise<{ slug: string }>;
6  searchParams: Promise<{ page?: string }>;
7}) {
8  const { slug } = await params;
9  const { page = '1' } = await searchParams;
10  return <Post slug={slug} page={Number(page)} />;
11}

4. Run the codemod and fix the rest

1npx @next/codemod@latest upgrade latest
2npm run lint && npm run build

Review the diff rather than trusting it blindly, especially around caching: see our article on Cache Components for the new opt-in model.

Checklist

• ☐ Node.js and TypeScript versions meet the new minimums
• ☐ middleware.ts renamed to proxy.ts
• ☐ All params / searchParams / cookies() awaited
• ☐ Build passes on Turbopack, or webpack opt-out is documented
• ☐ Caching behavior re-verified on key pages

Sources and further reading

• Next.js 16 upgrade guide