Plan an Upgrade to Next.js 16

The agent clones the repository into its own cloud sandbox and records the starting point before changing anything. In an app like shadcn-ui/taxonomy it reads package.json and finds next pinned to 13.3.2-canary.13, react and react-dom at ^18.2.0, typescript at 4.7.4, eslint 8 with eslint-config-next 13.0.0, next-auth 4.22.1, contentlayer and next-contentlayer ^0.3.1, @prisma/client and prisma ^4.13.0, and tailwindcss ^3.3.1. It finds .nvmrc at v16.18.0 and pnpm-lock.yaml at lockfileVersion: '6.0', so it installs with pnpm and notes that the Node version itself has to move before Next.js 16 will install. It runs pnpm build once on the untouched code so every later failure can be told apart from one that was already there.

Then it attempts the upgrade on a scratch branch: next@16, the React and React DOM versions Next.js 16 asks for, a matching eslint-config-next, and the official codemods from @next/codemod. It reads each place the new version disagrees with the code. In next.config.mjs that means experimental.appDir (the App Router is no longer behind a flag), experimental.serverComponentsExternalPackages, which became the top-level serverExternalPackages, and images.domains for avatars.githubusercontent.com, which the agent rewrites as images.remotePatterns. Route params become a Promise: the agent lists each params it finds, such as the PostPageProps interface in app/(marketing)/blog/[...slug]/page.tsx and the zod routeContextSchema that parses context.params in app/api/posts/[postId]/route.ts, and the synchronous headers() call on line 10 of app/api/webhooks/stripe/route.ts.

Some breaks are in tooling and dependencies, not code. The lint script is next lint, which Next.js 16 no longer ships, so ESLint has to run directly with a config that works for ESLint 9. middleware.ts wraps withAuth from next-auth/middleware, and the agent checks it against the middleware-to-proxy rename. next.config.mjs is wrapped in withContentlayer, which adds a webpack config while Next.js 16 builds with Turbopack by default, so the agent tries the build both ways and records which one works. next-auth 4.22.1 and next-contentlayer declare peer ranges for older Next.js, and app/api/og/route.tsx imports ImageResponse from @vercel/og ^0.0.21; the agent reports each peer conflict as the install prints it, and says whether the dependency has a release that supports Next.js 16 or needs replacing.

The repository has no test files, so the checks are the ones it can run: pnpm build (which runs contentlayer build and then next build), ESLint and tsc --noEmit. Because next.config.mjs imports ./env.mjs, which uses @t3-oss/env-nextjs to require DATABASE_URL, NEXTAUTH_SECRET, the Stripe and Postmark keys and more at build time, the agent sets placeholder values in the sandbox only and says so in the report. It fixes each break on the scratch branch just far enough to see the next one, so the report covers the whole chain instead of stopping at the first error. Nothing is pushed and no pull request is opened.

What comes back is upgrade-report.md as an artifact on the session, which the session read returns with a download link that works for an hour. It opens with the starting versions (Next.js, React, TypeScript, Node, ESLint) and the result of the untouched build, then lists each break with the file and line, the error text the build, ESLint or the type checker printed, the cause in one or two sentences, and an effort label. Breaks are grouped by kind: runtime and toolchain, next.config.mjs, async request APIs and route params, middleware and auth, content and image pipeline, and lint.

It ends with an ordered plan: what has to move first because everything else depends on it (Node and TypeScript before Next.js, a decision on Contentlayer before the build can pass), what a codemod handles, and what needs a person's judgment, such as replacing a dependency that has no release for Next.js 16. The session's transcript keeps every command the agent ran in the sandbox with its output, so each line of the report can be traced to the step that produced it.

Before planning the work from it, a reviewer checks the dependency recommendations against the team's own preferences, confirms that the placeholder environment did not hide a failure that only shows with real credentials, and decides whether to do the upgrade in one pull request or in the order the report gives. If the plan looks right, a follow-up message to the same session can ask the agent to carry out the first steps and open a pull request, since its sandbox still has the scratch branch.

Run it when the target moves. A small job on your server that watches the next package on npm, or a GitHub release notification for vercel/next.js, can send this request with the new version number in the prompt. Each run starts from a fresh clone of your default branch, so the report reflects the code as it is that day rather than when someone last looked.

Set a webhook URL on the API key and Rush POSTs run.completed when the run's turn finishes, with the session_url. Your server reads the session, takes the link to upgrade-report.md from its artifacts and opens a tracking issue with it, so the upgrade is planned from evidence instead of a changelog read.

Trying a major upgrade on a laptop means changing Node versions, reinstalling every dependency, fighting peer-range errors and then putting the machine back the way it was. In a Rush sandbox the agent changes the Node version, the lockfile and the config on its own disk, runs the build as many times as it takes, and nothing touches your checkout, your global toolchain or your branches.

An upgrade estimate is only as good as the evidence behind it. This report is built from real installs and real build, lint and type-check output, kept in the session's transcript, so the person planning the work can check any line against the command that produced it. Several reports can run at once, one per application, up to the key's concurrent run limit.

Will it change anything in my repository?

Does it work on a private repository?

My app has no tests. Is the report still useful?

Can it upgrade from Next.js 13 straight to 16?