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
.
Step 3 - Migrate package ESLint configurations
An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. You can read more about the new configuration setup in the build system documentation.
To migrate the ESLint configuration of all packages in your project, run the following command:
yarn backstage-cli migrate package-lint-configs
This will migrate all existing .eslintrc.js
that extend the old configuration from @backstage/cli
, as well as carry over any additional configuration.
Step 4 - Use backstage-cli repo
The Backstage CLI recently introduced a new repo
command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like lerna
, as they're able to avoid the overhead of calling package scripts through yarn
and can operate on multiple packages at once. You can read more about the repo
command in the CLI command documentation.
The way to execute this step of the migration is not as well defined as the previous steps, as it depends on what your development and CI/CD setup looks like. Look for the following patterns to replace in your root package.json
as well as CI/CD setup:
-
Commands that lint the entire repo should be replaced with
yarn backstage-cli repo lint
along with a--since
flag if needed. For example this:lerna run lint --since origin/master --
would be replaced by the following:
backstage-cli repo lint --since origin/master
-
In places where the entire repo is being built, use
yarn backstage-cli repo build
, which also supports the--since
flag. The migration here is a bit more nuanced as it depends on why you are building all packages.- If you are building all packages to verify that you are able to build them, you most likely want
backstage-cli repo build --all
. The--all
flag signals that bundled packages likepackages/app
andpackages/backend
should be built as well. Pair this up with a--since
flag in CI to avoid needing to build all packages. - If you are building all packages to publish them, then
backstage-cli repo build
is enough, as it builds all published packages. - If you are building all packages to deploy them, you likely don't want to use the
repo
command at all, simply callyarn build
in the packages you want to deploy instead. For example, if you are deploying the backend with a docker host build, it's enough to callyarn build
insidepackages/backend
. In a standard@backstage/create-app
there is also a shorthand for building the backend from the root,yarn build:backend
.
- If you are building all packages to verify that you are able to build them, you most likely want
FAQ
Why were package roles introduced?
To keep configuration lean, allow for more utilities and tooling, and to enable optimizations in the build system. You can read more about the reasoning in the original RFC.
Do I have to migrate to using package roles?
Short answer - yes.
Longer answer - mostly, you can get around having to declare the role of your packages by instead explicitly declaring the role in the command invocation or configuration. For example, the app:build
command will go away, but you can replace it with package build --role frontend
if you don't want to declare the role in package.json
. It is however strongly recommended to declare the package roles.
I have a package where none of the existing roles apply
The web-library
, node-library
and common-library
roles are general purpose roles that should cover most use cases. If you feel like none of those roles work for you, then please open an issue in the Backstage repo and suggest the addition of a new role.
Should I include the role in published packages?
Yes. While there is nothing that will consume the role at the moment, it is likely that future tooling will be able to provide a better experience for users when published packages include the role.