Skip to main content
Version: Next

Codemods

Audience: Developers and Admins

After you bump packages and review create-app / Upgrade Helper diffs, run recipes from the Backstage codemods repository. A recipe is an ordered set of source transforms on the Codemod Registry. You run it with the Codemod CLI.

This is not the old @backstage/codemods npm package. That package is gone from this repository.

There are two kinds of recipes:

  1. Versioned migration recipes fix mechanical breakage for a specific Backstage release (renames, API changes that shipped in that release, and similar).
  2. Misc recipes cover bigger migrations you schedule on your own timeline (for example Material-UI to Backstage UI).

Versioned migration recipes​

Include the versioned recipe for your target release in the upgrade. For release <major>.<minor>.0, the package name is @backstage/v<major>-<minor>-0-migration-recipe. Dry-run first, then apply:

# Example: upgrading toward Backstage 1.52.0
yarn dlx codemod run @backstage/v1-52-0-migration-recipe \
  --target . \
  --dry-run

yarn dlx codemod run @backstage/v1-52-0-migration-recipe \
  --target .

Skip this step if no recipe exists for your target version. Published recipes are listed in the codemods README.

After a recipe runs​

Search the repo for TODO(backstage-codemod) and resolve each marker. Read that recipe's README for anything left out of scope that you still need to change by hand.

Misc recipes​

Misc recipes are for migrations that do not belong to a single release. Skip them on a routine bump unless you intend that migration.

Material-UI 4 to Backstage UI​

The mui-to-bui-migration skill supports running this recipe and finishing its leftovers, or migrating directly with standalone guidance. It recommends the recipe for mechanical changes and honors your choice of path. The standalone path requires no codemod run.

To use the recipe, read the mui4-to-bui-migration-recipe README, then dry-run and apply:

yarn dlx codemod run @backstage/mui4-to-bui-migration-recipe \
  --target . \
  --dry-run

yarn dlx codemod run @backstage/mui4-to-bui-migration-recipe \
  --target .

Next steps​