Upgrading

Upgrading to 2.0

Update turbo.json

Get started upgrading from 1.x to 2.0 by running:

Terminal
npx @turbo/codemod migrate

This will update your turbo.json(s) for many of the breaking changes from 1.x to 2.0.

Additionally, a name field will be added to any package.json in the Workspace that doesn't have one.

Good to know:

You may also manually run each codemod individually. Visit the codemods page for more information.

Add a packageManager field to root package.json

The packageManager field is a convention from the Node.js ecosystem that defines which package manager is expected to be used in the Workspace.

Turborepo 2.0 requires that your Workspace define this field as a way to improve the stability and behavioral predictability of your codebase. If you do not have one already, add this field to your root package.json:

./package.json
{
+ "packageManager": "npm@10.8.1"
}

Update turbo run commands

Turborepo 2.0 includes behavioral and correctness improvements with behavior of turbo run commands. Listed below is the summary of changes, which may or may not have an affect on your codebase:

  • Strict Mode for environment variables is now the default, moving from Loose Mode (PR)
    • → If it appears that the scripts in your tasks are missing environment variables, you can opt back out of this behavior using the --env-mode option on a per-command basis to incrementally migrate. We encourage you to update the env key in your task to account for all of its environment variables so you can drop the --env-mode option as soon as possible.
  • Workspace root directory is now an implicit dependency of all packages (PR)
    • → The repository should have as little code in the root as possible, since changes to the root can affect all tasks in your repository. Additionally, if you're using Internal Packages in the Workspace root, changes to those dependencies will also cause cache misses for all tasks. In both cases, consider moving the code out of the root and into a package.
  • --ignore removed in favor of --filter and graph correctness changes below (PR)
  • Removed --scope flag (deprecated since 1.2) (PR)
  • engines field in root package.json is now used in hashing (PR)
  • --filter no longer infers namespaces for package names (PR)
  • --filter now errors when no package names or directories are matched (PR)
  • --only restricts task dependencies instead of package dependencies (PR)

hours

Total Compute Saved
Get started with
Remote Caching →

On this page