A shortened version of the full walkthrough: Next.js 16 upgrade: async params, proxy.ts, and Turbopack build breaks.
Next.js 16 finished three migrations that 15 only warned about. Upgrade a real app and you meet them in the first build:
| Change | What you see | Fix |
|---|---|---|
| Request APIs are Promises | Route "/blog/[slug]" used "params.slug" directly |
await in server components, use() in client components |
| Turbopack is the default | Webpack is configured while Turbopack is not |
next build --webpack, or migrate to turbopack.rules
|
middleware.ts → proxy.ts
|
deprecated warning, then your auth gate silently stops running | rename the file and the export, Node runtime only |
1. params and searchParams are Promises
In 15 a thenable proxy let params.slug resolve synchronously. 16 removed the proxy, so the value is undefined and the error surfaces wherever it is finally used — a params.slug three files deep looks like a routing bug.
// before (Next.js 15)
export default function Page({ params }: { params: { slug: string } }) {
return <h1>{params.slug}</h1>;
}
// after (Next.js 16) — await in server components
export default async function Page(props: PageProps<'/blog/[slug]'>) {
const { slug } = await props.params;
return <h1>{slug}</h1>;
}
PageProps<'/route'> comes from npx next typegen, which writes .next/types. The same rule applies to cookies(), headers() and draftMode():
const token = (await cookies()).get('session')?.value;
Client components cannot await, so they unwrap with React's use() during render. Prefer awaiting on the server and passing the value down.
2. Turbopack and proxy.ts
A leftover webpack key fails the build on purpose:
// next.config.js — fails "next build" in 16
module.exports = { webpack: (config) => { /* ... */ return config; } };
Two ways out: "build": "next build --webpack" while you find the plugin that added the key, or migrate the loader:
module.exports = {
turbopack: { rules: { '*.svg': { loaders: ['@svgr/webpack'], as: '*.js' } } },
};
The rename is the dangerous one because nothing fails:
// proxy.ts — Node.js runtime, same handler shape
import { NextResponse, type NextRequest } from 'next/server';
export function proxy(request: NextRequest) {
if (!request.cookies.get('session')) {
return NextResponse.redirect(new URL('/login', request.url));
}
return NextResponse.next();
}
Renaming the file but leaving export function middleware gives you a proxy file with no proxy: every request passes through, silently. proxy.ts also cannot use export const runtime = 'edge', and skipMiddlewareUrlNormalize became skipProxyUrlNormalize.
3. Order of operations
npx @next/codemod@canary upgrade latestnpx @next/codemod@canary next-async-request-api .npx next typegen && npx tsc --noEmit- Rename
middleware.ts→proxy.tsand changeexport function middlewaretoexport function proxy— otherwise the file exists and nothing runs. - Add a
default.js(returningnull) to every parallel route slot; the build fails without one.
Leave cacheComponents: true off until the build is green. It is a caching redesign, not a checkbox: dynamic, revalidate and fetchCache exports start erroring and use cache becomes the way to cache. Minimum versions moved too — Node.js 20.9+ and TypeScript 5.1+.
Tooling that helps
All client-side, nothing uploaded: JSON formatter · YAML ↔ JSON · diff checker · cURL → fetch / Python / Go.
Top comments (0)