Backstage is always improving, so it's a good idea to stay in sync with the
latest releases. Backstage is more of a library than an application or service;
@backstage/create-app tool gives you a
starting point that's meant to be evolved.
Updating Backstage versions with backstage-cli
The Backstage CLI has a command to bump all
@backstage packages and
dependencies you're using to the latest versions:
yarn backstage-cli versions:bump
The reason for bumping all
@backstage packages at once is to maintain the
dependencies that they have between each other.
Following create-app template changes
@backstage/create-app command creates the initial structure of your
Backstage installation from a template. The source of this template in the
Backstage repository is updated periodically, but your local
packages are established at
create-app time and won't automatically get these
For this reason, any changes made to the template are documented along with
upgrade instructions in the
@backstage/create-app package. We recommend peeking at this changelog
for any applicable updates when upgrading packages.
More information on dependency mismatches
Backstage is structured as a monorepo with
Yarn workspaces. This means
backend packages, as well as any custom plugins you've added,
are separate packages with their own
package.json and dependencies.
When a given dependency version is the same between different packages, the
dependency is hoisted to the main
node_modules folder in the monorepo root to
be shared between packages. When different versions of the same dependency are
encountered, Yarn creates a
node_modules folder within a particular package.
This can lead to confusing situations with type definitions, or anything with global state. React Context, for example, depends on global referential equality. This can cause problems in Backstage with API lookup, or config loading.
To help resolve these situations, the Backstage CLI has
will validate versions of
@backstage packages in your app to check for
# Add --fix to attempt automatic resolution in yarn.lock yarn backstage-cli versions:check