@turbo/codemod - Turborepo

Turborepo provides codemod transformations and automatic migration scripts to help upgrade your Turborepo codebase when a feature is deprecated.

Codemods are transformations that run on your codebase programmatically. This allows for a large amount of changes to be applied without having to manually manage repetitive changes.

Usage

First, ensure that you've run your package manager's install command.

bash

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

transform - name of transform, see available transforms below.
path - files or directory to transform
--dry - Do a dry-run (Code will not be edited)
--print - Prints the changed output for comparison

Upgrading Turborepo versions

In most cases, you can run:

bash

npx @turbo/codemod migrate

All the codemods you need to upgrade will be run for you.

Turborepo 2.x

The codemods below are used for migration paths in the second major version of Turborepo.

Updates the $schema URL in turbo.json files to use the versioned subdomain format. This applies to both root and workspace turbo.json files.

bash

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

Example

diff

{
- "$schema": "https://turborepo.dev/schema.json",
+ "$schema": "https://v2-7-5.turborepo.dev/schema.json",
}

</Accordion> <Accordion title="update-schema-json-url (2.0.0)" id="update-schema-json-url">

Updates a versioned schema.json URL to v2.

bash

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

Example

diff

{
- "$schema": "https://turborepo.dev/schema.v1.json",
+ "$schema": "https://turborepo.dev/schema.v2.json",
}

</Accordion> <Accordion title="add-package-names (2.0.0)" id="add-package-names">

Adds a name to package.json in any packages that don't have one.

bash

npx @turbo/codemod add-package-names

Example

diff

{
+ "name": "@repo/ui",
}

</Accordion> <Accordion title="clean-globs (2.0.0)" id="clean-globs">

Fix glob patterns that are invalid due to changes in processing of globs in turbo.

bash

npx @turbo/codemod clean-globs

Example

diff

{
  "tasks": {
    "build": {
      "outputs": [
        // Collapse back-to-back doublestars
-         "**/**.ext", // [!code highlight]
+         "**.ext" // [!code highlight]
        // Ensure a file extension does not have a double-star
-         "**.ext", // [!code highlight]
+         "**/*.ext" // [!code highlight]
        // Proper expansion of directory names
-         "prefix**/", // [!code highlight]
+         "prefix*/**" // [!code highlight]
      ]
    }
  }
}

</Accordion> <Accordion title="migrate-dot-env (2.0.0)" id="migrate-dot-env">

Move .env files from the removed dotEnv key to inputs.

bash

npx @turbo/codemod migrate-dot-env

Example

diff

{
  "tasks": {
    "build": {
-       "dotEnv": [".env"], // [!code highlight]
      "inputs": [
        "dist/**",
+         ".env" // [!code highlight]
      ],
    }
  }
}

</Accordion> <Accordion title="rename-output-mode (2.0.0)" id="rename-output-mode">

Rename the outputMode key to outputLogs.

bash

npx @turbo/codemod rename-output-mode

Example

diff

{
  "tasks": {
    "build": {
-     "outputMode": "errors-only" // [!code highlight]
+     "outputLogs": "errors-only" // [!code highlight]
    }
  }
}

</Accordion> <Accordion title="rename-pipeline (2.0.0)" id="rename-pipeline">

Rename the pipeline key to tasks.

bash

npx @turbo/codemod rename-pipeline

Example

diff

{
- "pipeline": {
+ "tasks": {
    "build": {
      ...
    },
    "dev": {
      ...
    },
    "lint": {
      ...
    }
  }
}

</Accordion> <Accordion title="stabilize-ui (2.0.0)" id="stabilize-ui">

Renames the experimentalUI key in turbo.json to ui.

bash

npx @turbo/codemod stabilize-ui

Example

diff

{
- "experimentalUI": true
+ "ui": true
}

</Accordion> </Accordions>

Turborepo 1.x

The codemods below are used for migration paths in the first major version of Turborepo.

Migrates turbo.json's experimentalGlobalPassThroughEnv to globalPassThroughEnv and experimentalPassThroughEnv to passThroughEnv.

bash

npx @turbo/codemod stabilize-env-mode

Example

diff

{
  "$schema": "https://turborepo.dev/schema.json",
- "experimentalGlobalPassThroughEnv": ["CC"],
+ "globalPassThroughEnv": ["CC"],
  "pipeline": {
    "build": {
-     "experimentalPassThroughEnv": ["GOROOT"],
+     "passThroughEnv": ["GOROOT"],
    }
  }
}

</Accordion> <Accordion title="transform-env-literals-to-wildcards (1.10.0)" id="transform-env-literals-to-wildcards">

Updates any existing environment variable fields whose contents would be ambiguous to the new wildcard syntax.

bash

npx @turbo/codemod transform-env-literals-to-wildcards

Example

diff

{
  "$schema": "https://turborepo.dev/schema.json",
- "globalEnv": ["THIS_*_IS_LITERAL"],
- "globalPassThroughEnv": ["!LITERAL_LEADING_EXCLAMATION"],
+  "globalEnv": ["THIS_\\*_IS_LITERAL"],
+  "globalPassThroughEnv": ["\\!LITERAL_LEADING_EXCLAMATION"],
  "pipeline": {
    "build": {
-     "env": ["50_PERCENT_OFF*_HAS_SMALL_PRINT"],
-     "passThroughEnv": ["**BOLDED**"],
+     "env": ["50_PERCENT_OFF\\*_HAS_SMALL_PRINT"],
+     "passThroughEnv": ["\\*\\*BOLDED\\*\\*"],
    }
  }
}

</Accordion> <Accordion title="set-default-outputs (1.7.0)" id="set-default-outputs">

Migrates turbo.json outputs to include the previously inferred dist/** and build/**.

bash

npx @turbo/codemod set-default-outputs

Example

diff

{
  "$schema": "https://turborepo.dev/schema.json",
  "globalDependencies": [".env"],
  "globalEnv": ["CI_ENV"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["API_BASE"],
      "outputs": [".next/**", "!.next/cache/**", "!.next/dev/**"]
    },
-   "lint": {
-     "outputs": []
-    },
+   "lint": {},
    "dev": {
      "cache": false,
      "persistent": true,
+     "outputs": ["dist/**", "build/**"]
    }
  }
}

</Accordion> <Accordion title="migrate-env-var-dependencies (1.5.0)" id="migrate-env-var-dependencies">

Migrates all environment variable dependencies in turbo.json from dependsOn and globalDependencies to env and globalEnv respectively.

bash

npx @turbo/codemod migrate-env-var-dependencies

Example

diff

// After, turbo.json
{
  "$schema": "https://turborepo.dev/schema.json",
- "globalDependencies": [".env", "$CI_ENV"],
+ "globalDependencies": [".env"],
+ "globalEnv": ["CI_ENV"],
  "pipeline": {
    "build": {
-     "dependsOn": ["^build", "$API_BASE"],
+     "dependsOn": ["^build"],
+     "env": ["API_BASE"],
      "outputs": [".next/**", "!.next/cache/**", "!.next/dev/**"],
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

</Accordion> <Accordion title="add-package-manager (1.1.0)" id="add-package-manager"> Transforms the root `package.json` so that `packageManager` key as the detected package manager (`yarn`, `npm`, `pnpm`) and version (e.g. `[email protected]`). This key is now [supported by Node.js](https://nodejs.org/dist/latest-v17.x/docs/api/packages.html#packagemanager) and is used by Turborepo for faster package manager detection (vs. inferring from just the filesystem alone).

bash

npx @turbo/codemod add-package-manager

Example

diff

{
  "name": "turborepo-basic",
  "version": "0.0.0",
  "private": true,
+  "packageManager": "[email protected]",
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

</Accordion> <Accordion title="create-turbo-config (1.1.0)" id="create-turbo-config">

Creates the turbo.json file at the root of your project based on the "turbo" key in package.json. The "turbo" key is subsequently deleted from package.json.

bash

npx @turbo/codemod create-turbo-config

Example

diff

// After, package.json
{
  "name": "@acme/workspace",
  "private": true,
- "turbo": {
-   "pipeline": {
-     ...
-   }
- },
}

</Tab> <Tab value="turbo.json"> ```diff title="./turbo.json" + { + "$schema": "https://turborepo.dev/schema.json", + "pipeline": { + ... + } + } ``` </Tab> </Tabs> </Accordion> </Accordions>