Package Role Migration
The Backstage CLI has introduced the concept of package roles, whose purpose is to enable more powerful tooling, optimizations, and leaner package configuration. More background and information about the change can be found in the original RFC and the FAQ on this page.
Package roles are implemented through a well-known "backstage"."role"
field in the
package.json
of each package. There are a handful of roles defined so far, and it
is not possible to use values outside the set of predefined roles.
With roles in place in all packages, the Backstage CLI is able to automatically
determine how to handle each package. For example, the different build commands
have been replaced by a single one that instead knows how to build each role.
The test and lint configurations are also selected automatically based on the role, and
a new category of repo
commands have been introduced in the CLI, which are able
to operate across all packages simultaneously.
Package roles have been used in the Backstage main repository for a while, and we now recommend that all Backstage projects are migrated to use package roles.
Migration
In order to make the migration as smooth as possible @backstage/cli
provides
a number of migration utilities. Using these in combination with some manual review
and optional steps should be all you need to migrate to package roles in most projects.
Before you begin the migration, make sure you have updated to the most recent version of
the @backstage/cli
.
TL;DR, Step 1-4:
This is a shorter version of all of the steps below, in case you're in a hurry.
Run the following commands:
yarn backstage-cli migrate package-roles
yarn backstage-cli migrate package-scripts
yarn backstage-cli migrate package-lint-configs
Have a look at the new commands under yarn backstage-cli repo
, and switch to them wherever you can. They tend to be much faster compared to their lerna
equivalents.
Step 1 - Add package roles
The first step is to add the "backstage"."role"
field to each package. This can of course be done manually, but the following command will attempt to automatically detect the role of each package in your project:
yarn backstage-cli migrate package-roles
The automatic detection is not perfect, so it is recommended to manually review the roles that were assigned to each package. You can use the package role definitions as a reference.
Step 2 - Migrate package scripts
The migration to package roles also introduces a new package
command category to the CLI.
Each command under the package
category is designed to be mapped directly to an entry in "scripts"
in package.json
. These commands replace the existing commands like build
, app:build
, lint
, and test
. They look something like this:
{
"scripts": {
"start": "backstage-cli package start",
"build": "backstage-cli package build",
"lint": "backstage-cli package lint",
...
}
}
Every package role has a fixed set of recommended scripts. It is strongly recommended that you use these scripts, as it allows for optimizations in other parts of the CLI. You can migrate to using all of these scripts by running the following command:
yarn backstage-cli migrate package-scripts
The migration command also carries over any existing flags that were being passed in the old scripts.
If you in the end do not want to use this exact script setup, it is still recommended to migrate to using the package
commands, as the top-level commands will be deprecated and removed. If you don't want to use package roles either, you can pass an explicit role to some of the package commands, for example yarn backstage-cli package build --role web-library
.