Dev.to WebDev ๐Ÿ›  Dev ๐Ÿ‘ 0 ๐Ÿ“– 2 min read

Next.js 16 upgrade: async params, proxy.ts, and the Turbopack build break

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 i

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

  1. npx @next/codemod@canary upgrade latest
  2. npx @next/codemod@canary next-async-request-api .
  3. npx next typegen && npx tsc --noEmit
  4. Rename middleware.ts โ†’ proxy.ts and change export function middleware to export function proxy โ€” otherwise the file exists and nothing runs.
  5. Add a default.js (returning null) 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.

๐Ÿ“ฐ Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes โ€” full credit and traffic to the original publisher.