DEV Community

R (RYUSLOG DEV)
R (RYUSLOG DEV)

Posted on Originally published at ryuslog.com

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 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>;
}
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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; } };
Enter fullscreen mode Exit fullscreen mode

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' } } },
};
Enter fullscreen mode Exit fullscreen mode

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();
}
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)