next-codemod

Purpose

@next/codemod ships the jscodeshift-based transforms that upgrade user code between Next.js major versions. It is what next upgrade runs under the hood, and is also installable directly as a CLI: npx @next/codemod <transform> <path>.

Source: packages/next-codemod/.

Directory layout

packages/next-codemod/
├── README.md
├── bin/                     # CLI entry
├── lib/                     # Shared helpers (parsing, file walking)
├── transforms/              # One directory per transform
├── scripts/                 # Maintenance scripts
├── package.json
└── turbo.json

Each subdirectory of transforms/ is one named codemod: a transform script plus its test fixtures. jscodeshift visits each file in the user's project, parses it to an AST, runs the transform, and writes back the result.

Examples of transforms

The catalog grows with each release. Examples that have shipped:

• name-default-component — gives anonymous default-exported page components a stable name
• new-link — converts old <Link><a/></Link> patterns to the modern <Link> shape
• next-image-to-legacy-image — moves users off next/image onto next/legacy/image where applicable
• next-image-experimental — opts code into the (now-default) next/image
• app-dir-runtime-config-experimental — migrates runtime config to the App Router shape
• built-in-next-font — rewrites third-party @next/font imports to the built-in next/font
• cra-to-next — migrates Create React App projects to Next.js
• metadata-to-viewport-export — splits viewport out of metadata per the App Router schema

The transform README lists the canonical set; new entries are added as the framework deprecates APIs.

How next upgrade invokes it

packages/next/src/cli/next-upgrade.ts shells out to npx @next/codemod with the right transform name when you run next upgrade. The upgrade flow:

graph LR
    User[next upgrade] --> CLI[cli/next-upgrade.ts]
    CLI --> Detect[detect installed Next.js version]
    Detect --> Plan[plan upgrade path]
    Plan --> Bump[bump package.json]
    Bump --> Run[run codemods for each version step]
    Run --> Codemod[@next/codemod transforms]

Adding a new codemod

To add a transform:

1. Create packages/next-codemod/transforms/<name>/ with index.ts (the jscodeshift visitor) and __testfixtures__/ (input/output pairs).
2. Add an entry to the codemod README and the next upgrade plan.
3. Ship a release.

Tests are run with jscodeshift --runInBand inside the package's own test runner.

Key source files

File	Purpose
packages/next-codemod/bin/	CLI entry script
packages/next-codemod/lib/	Shared helpers (file walkers, parsers)
packages/next-codemod/transforms/<name>/index.ts	One transform per directory
packages/next/src/cli/next-upgrade.ts	The framework-side next upgrade driver