next-upgrade

name	next-upgrade
version	1.1.0
description	Structured workflow for upgrading Next.js applications across major versions. Use when migrating a Next.js project from one major version to another (e.g., 13 to 14, 14 to 15, 15 to 16). Covers codemod automation, breaking change detection, incremental migration paths, and post-upgrade validation.
license	MIT
category	Frameworks
tags	["nextjs","upgrade","migration","codemod","breaking-changes"]
agents	["nextjs-pro","developer","devops"]
tools	["Read","Write","Edit","Bash"]
invoked_by	Skill({ skill: 'next-upgrade' })
user_invocable	true
metadata	{"author":"vercel-labs","source":"vercel-labs/next-skills"}
verified	true
lastVerifiedAt	"2026-02-22T00:00:00.000Z"
source	builtin
trust_score	100
provenance_sha	26f89a058b387527

Next.js Upgrade Workflow

Structured 9-step workflow for upgrading Next.js applications across major versions. Handles codemod automation, dependency updates, breaking change resolution, and validation.

When to Apply

Use this skill when:

• Upgrading Next.js to a new major version (13, 14, 15, 16)
• Running codemods to automate breaking change migrations
• Resolving deprecation warnings in an existing Next.js project
• Planning an incremental migration path for large codebases
• Validating that an upgrade did not introduce regressions

9-Step Upgrade Workflow

Step 1: Detect Current Version

Identify the current Next.js version and target version.

# Check current version
cat package.json | grep '"next"'

# Check Node.js version (Next.js 15+ requires Node 18.18+, Next.js 16 requires Node 20+)
node --version

Version Requirements:

Next.js	Minimum Node.js	Minimum React
13	16.14	18.2.0
14	18.17	18.2.0
15	18.18	19.0.0
16	20.0	19.0.0

Step 2: Create Upgrade Branch

git checkout -b upgrade/nextjs-{target-version}

Always upgrade on a dedicated branch. Never upgrade on main directly.

Step 3: Run Codemods

Use the official Next.js codemod CLI to automate breaking change migrations.

# Interactive mode (recommended) -- selects applicable codemods
npx @next/codemod@latest upgrade latest

# Or target a specific version
npx @next/codemod@latest upgrade 15
npx @next/codemod@latest upgrade 16

Key Codemods by Version:

Next.js 13 to 14

• next-image-to-legacy-image -- Renames next/image imports to next/legacy/image
• next-image-experimental -- Migrates from next/legacy/image to new