Migrating to Next.js 16: A Practical Upgrade Guide

Next.js 16 is the biggest release since the App Router landed, and the upgrade is not a one-line bump. The caching model changed shape, params and searchParams are now promises everywhere, Turbopack runs your builds by default, and middleware.ts is on its way out in favour of proxy.ts . None of that is hard on its own. The trouble is that the changes touch almost every dynamic route in a real app at once, so a rushed upgrade tends to fail in a dozen small places rather than one obvious one. We run this site on Next.js 16, and we have moved client projects across the same gap. The pattern that works is boring and reliable: read the codemod output, fix the async APIs first, decide your caching strategy deliberately instead of letting the old implicit behaviour leak back in, then clean up the renamed files. This guide walks through that order, with the specific gotchas that cost the most time. If you are still on Next.js 13 or 14, the same steps apply, you just have more of them to work through. Run the codemod, then read what it could not fix Start with the official upgrade command. It pulls the right versions of next , react , and react-dom , and runs the codemods that handle the mechanical rewrites for you. npx @next/codemod@latest upgrade latest The codemod is good, but it is not magic. It will happily wrap your params access in await where the shape is obvious, and skip anything indirect, a params object passed into a helper, destructured two functions deep, or read inside a generateMetadata you wrote by hand. Treat the codemod as the first 80%, not the finish line. Once it has run, do a clean install and a type check before you touch anything else. With typescript.ignoreBuildErrors set, as it is on many projects, the build will not catch these for you, so run the type checker yourself. rm -rf node_modules .next && npm install && npx tsc --noEmit The errors that come back are your real to-do list. Most of them will be the async API change, which is the next sectio