# Upgrade Next.js Projects Safely

Next.js upgrades can involve breaking changes, codemods, and dependency coordination. This skill guides Claude, Codex, or Claude Code through official migration steps and validation checks.

## Install

```bash
npx skillstore add vercel-labs/next-upgrade
```

## Metadata

- Status: approved
- Slug: vercel-labs-next-upgrade
- Skillstore revision: r1
- Version status: missing
- Tree hash: 19aee1ef70ce5e1b13e562f34a845d78b5013380a91e428dd42d9a8c38dd346c
- Author: vercel-labs
- GitHub username: vercel-labs
- License: MIT
- Repository: https://github.com/vercel-labs/next-skills/tree/main/skills/next-upgrade/
- Ref: 26421118b848d9f1efc0aa169d8a7a9e7e0a877e
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands, network
- Quality score: 69
- Public page: https://skillstore.pages.dev/skills/vercel-labs-next-upgrade
- Manifest: https://skillstore.pages.dev/api/skills/vercel-labs-next-upgrade/manifest

## Capabilities

- Reads package.json to identify the current Next.js and React versions.
- Fetches official Next.js migration and codemod documentation.
- Builds an incremental upgrade path for major version changes.
- Suggests relevant Next.js codemods before manual edits.
- Updates Next.js, React, React DOM, and related TypeScript packages.
- Runs build and development checks after migration changes.

## Use Cases

- Plan a Version Upgrade: Create a clear migration path from the current Next.js version to the requested target version.
- Apply Official Codemods: Select relevant codemods, run them with approval, and review generated source changes.
- Validate Release Readiness: Run post-upgrade checks and summarize remaining build, type, or runtime issues.

## Prompt Templates

### Inspect Upgrade Needs

```
Use the next-upgrade skill to inspect this repository and identify the current Next.js, React, and React DOM versions.
```

### Plan a Major Upgrade

```
Use the next-upgrade skill to plan an incremental upgrade path to the latest stable Next.js release. Do not change files yet.
```

### Run Codemods With Review

```
Use the next-upgrade skill to find applicable codemods, ask before running commands, then summarize every generated change.
```

### Complete a Complex Migration

```
Use the next-upgrade skill to upgrade this app, handle manual breaking changes, update dependencies, and report validation results.
```

## Limitations

- It depends on official documentation being reachable during the session.
- It cannot guarantee npm packages or project scripts are safe to execute.
- It may need manual follow-up for custom routing, configuration, or APIs.
- It does not replace application-specific regression testing.

## Best Practices

- Review the proposed upgrade path before allowing package manager commands.
- Commit or stash local work before running codemods or dependency updates.
- Run application tests after the build succeeds.

## Anti Patterns

- Running unpinned package commands without reading the migration plan.
- Skipping manual review of codemod-generated source changes.
- Treating a successful build as complete release validation.

## Security Audit

- Audited at: 2026-07-09T14:10:36.045\+00:00
- Summary: The skill is a normal Next.js upgrade workflow and contains no prompt injection or data-exfiltration language. The main risk is that it instructs agents to run unpinned npm and npx commands plus project scripts, which can execute third-party or repository-controlled code. The hardcoded URLs point to official Next.js documentation and are not suspicious.

## Stats

- Views: 145
- Downloads: 7
- Favorites: 0
- Popularity score: 0