@turbo/codemod

Purpose and Scope

@turbo/codemod is Turborepo’s migration utility for applying repository changes when a Turborepo feature is deprecated, renamed, or moved into a new configuration shape. A codemod is a programmatic transformation: instead of asking every team to edit repeated package.json, turbo.json, or workspace files by hand, the package runs a named transform against a target path and updates matching files. The first-party reference describes this as both a transform runner and an automatic migration system for Turborepo version upgrades.

Sources: apps/docs/content/docs/reference/turbo-codemod.mdx

Use this reference when you are upgrading Turborepo, reviewing a pull request produced by a migration, or deciding whether a change belongs in a manual edit or a codemod run. The safe workflow is intentionally simple: install dependencies first, run the migration command or a specific transform, inspect the diff, and then run the normal Turborepo validation tasks for the repository. The command supports dry-run and print modes so you can preview edits before committing them.

Sources: apps/docs/content/docs/reference/turbo-codemod.mdx, apps/docs/content/blog/turbo-1-1-0.mdx

Relevant Source Files

• apps/docs/content/docs/reference/turbo-codemod.mdx — The primary reference page for @turbo/codemod, including usage syntax, migration entry point, options, and documented transform examples.
• apps/docs/content/blog/turbo-1-1-0.mdx — Release notes that introduced automatic migrations as official, idempotent code transformations and showed the early command contract.
• apps/docs/content/blog/turbo-1-10-0.mdx — Release notes that told users to update with npx @turbo/codemod migrate and connected migrations to changes such as generators and environment-variable behavior.
• apps/docs/content/blog/turbo-0-4-0.mdx — Historical context for older configuration and pipeline concepts that later migrations needed to preserve or evolve.
• apps/docs/content/blog/joining-vercel.mdx — Historical context for the open-source CLI and Vercel-backed Turborepo era that shaped the public migration story.
• apps/docs/content/blog/free-vercel-remote-cache.mdx — Context for modern Turborepo workflows where upgrades often happen alongside Vercel Remote Cache and CI environment configuration.

Command Reference

The general command form is npx @turbo/codemod [transform] [path] [--dry] [--print]. The transform argument selects the named codemod. The path argument points at the files or directory to transform, which lets you run against a whole repository or constrain the edit to a subdirectory while reviewing a migration. The --dry flag performs a dry run without editing files, and --print prints changed output for comparison. The docs also instruct users to run their package manager’s install command before invoking the codemod, which helps ensure the package manager state and workspace metadata are ready for analysis.

Sources: apps/docs/content/docs/reference/turbo-codemod.mdx

npx @turbo/codemod [transform] [path] [--dry] [--print]

For version upgrades, the recommended default is the migration entry point rather than hand-picking every transform. Running npx @turbo/codemod migrate lets Turborepo run the codemods needed for the upgrade path. This is the command shown in the reference page under upgrading Turborepo versions, and it is also used in the Turborepo 1.10 release notes as the update command. Prefer this path when you are moving a repository forward by version and do not already know the exact transform names required.

Sources: apps/docs/content/docs/reference/turbo-codemod.mdx, apps/docs/content/blog/turbo-1-10-0.mdx

npx @turbo/codemod migrate

Migration Workflow

A practical upgrade flow starts on a clean branch. First, install dependencies with the repository’s package manager so workspace metadata and lockfiles reflect the current state. Next, run npx @turbo/codemod migrate from the root and inspect the generated diff. If the migration touches important configuration, run it again with --dry or rerun a single named transform with --print to understand the edit shape. After accepting the changes, run the repository’s usual turbo run build, turbo run test, lint, or CI tasks so the migration is validated by the same task graph used in day-to-day development.

Sources: apps/docs/content/docs/reference/turbo-codemod.mdx, apps/docs/content/blog/turbo-1-1-0.mdx

The release notes for Turborepo 1.1 are important because they describe automatic migrations as official idempotent migration scripts. Idempotent means the transform is intended to be safe to run more than once without repeatedly corrupting or duplicating the same change. That property matters during upgrades because a team may test a migration locally, rerun it in CI, or ask multiple maintainers to reproduce the result. The same release introduced turbo.json as the configuration home, showing why codemods are useful: configuration moves are repetitive and easy to get subtly wrong by hand.

Sources: apps/docs/content/blog/turbo-1-1-0.mdx

Turborepo 2.x Transform Examples

The 2.x migration section groups transforms used for the second major version of Turborepo. update-versioned-schema-json updates $schema URLs in root and workspace turbo.json files to the versioned subdomain format, for example from https://turborepo.dev/schema.json to https://v2-7-5.turborepo.dev/schema.json. update-schema-json-url updates an older versioned schema URL to the v2 schema URL. These transforms do not change task semantics directly; they make editor validation and schema discovery match the Turborepo version being targeted.

Sources: apps/docs/content/docs/reference/turbo-codemod.mdx

npx @turbo/codemod update-versioned-schema-json
npx @turbo/codemod update-schema-json-url

Some transforms normalize package and glob configuration. add-package-names adds a name field to package manifests that do not have one, with the documented example producing a scoped name such as @repo/ui. clean-globs fixes glob patterns that became invalid due to changes in Turborepo glob processing. The examples include collapsing back-to-back doublestars, ensuring file extensions are matched through a directory glob, and expanding directory prefixes into a supported pattern shape. These changes are small, but they affect how tasks discover inputs and outputs.

Sources: apps/docs/content/docs/reference/turbo-codemod.mdx

npx @turbo/codemod add-package-names
npx @turbo/codemod clean-globs

Other visible 2.x transforms move configuration keys to their newer homes. migrate-dot-env moves .env files from the removed dotEnv key into inputs, preserving the intent that those files participate in task hashing. rename-output-mode renames outputMode to outputLogs, keeping the configured logging behavior while updating the field name. These transforms are good examples of why codemods exist: the user’s desired behavior remains recognizable, but the syntax needs to follow the current turbo.json contract.

Sources: apps/docs/content/docs/reference/turbo-codemod.mdx

npx @turbo/codemod migrate-dot-env
npx @turbo/codemod rename-output-mode

Historical Context and Compatibility Signals

Turborepo’s migration story reflects the project’s evolution. Turborepo 0.4.0 introduced major build-system changes such as a Go rewrite, smarter hashing, pruned workspaces, pipeline configuration, and per-task cache outputs. Later, Turborepo 1.1 highlighted automatic migrations, turbo.json, package manager detection through the root packageManager key, environment variable dependencies, and partial Yarn v2 support. These releases show why codemods are not cosmetic: as the build system changes its configuration model, migrations help preserve intent across task orchestration, hashing, caching, and workspace layout changes.

Sources: apps/docs/content/blog/turbo-0-4-0.mdx, apps/docs/content/blog/turbo-1-1-0.mdx

The Vercel-era blog posts provide additional context for how upgrades fit into real repositories. The acquisition post announced the CLI as open source and described Vercel-backed remote caching. The later free Remote Cache post explains that repositories linked to Vercel can use Vercel Remote Cache, with CI authentication through TURBO_TOKEN and TURBO_TEAM, and local setup through npx turbo login and npx turbo link. Codemods do not replace those cache commands, but upgrades frequently happen in the same maintenance window as CI and remote-cache configuration review.

Sources: apps/docs/content/blog/joining-vercel.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

Operational Guidance

Treat codemod output like source code. Review generated diffs, keep the changes in a dedicated commit when possible, and avoid mixing an upgrade migration with unrelated refactors. If a transform changes turbo.json, pay special attention to task inputs, outputs, logging keys, and schema URLs because those fields affect cache keys, task output restoration, and editor validation. If a transform changes package.json, verify package names and workspace boundaries before publishing or running package-scoped commands.

Sources: apps/docs/content/docs/reference/turbo-codemod.mdx, apps/docs/content/blog/turbo-1-1-0.mdx

After a migration, run the commands that prove the repository still behaves as expected. For most Turborepo users, that means executing representative turbo run tasks, checking CI configuration, and confirming remote cache authentication if the repository depends on shared cache artifacts. If the migration was part of a major version upgrade, read the related reference pages for turbo.json configuration, glob syntax, environment variables, and command behavior before accepting surprising diffs. The next useful pages are configuration, globs, environment-variables, run-command, and remote-caching.