Skip to main content
Pre-built plugin installation is being rolled out gradually and might not be available in your instance yet. Look for the Custom Plugins tab under Admin → Plugin Settings. If the tab is not present, follow the previous installer instructions. See Switching to pre-built plugins for rollout details and help moving existing plugins.

​
Choose a version

Pre-built plugins support stable releases. When installing or updating a package, use one of these forms:
  • @backstage/plugin-example or @backstage/plugin-example@latest — resolve the latest stable release available through Portal.
  • @backstage/plugin-example@1.2.3 — request an exact stable version.
The requested release must be available as a pre-built plugin. Portal keeps a limited selection of prepared releases, so an older version on npm may not be available to install. Prerelease versions such as 2.0.0-beta.1, npm dist-tags other than latest (such as next or beta), and semver ranges such as ^1.2.0 are not supported for pre-built installation.

​
Checking for updates

Portal checks for newer stable versions of installed pre-built plugins. Review the proposed package versions before applying an update; an update may include a new major version with changes that require configuration or other setup. Portal can also offer a new revision of the same npm version. A revision contains newly prepared artifacts without changing the plugin’s published version number. These updates appear as Install new revision or Install new revisions and use the same update controls.

​
Experimental versions

To try a prerelease or experimental version, package it as a custom plugin and publish it from a Backstage workspace:
  1. Check out the plugin source at the version or commit you want to test.
  2. Prepare the workspace and test its frontend and backend features with Portal Studio.
  3. Create a publishing source and token, then publish and install the workspace.
  4. Verify the active source version and test the plugin in your Portal instance.
Custom plugins are released as source versions, rather than selected through npm dist-tags. Publish another source version to update the plugin, or pin a retained source version to roll back. Your organization is responsible for testing and maintaining the experimental code it publishes.

​
Using the previous installer

The previous installer supports exact stable versions and prerelease versions such as 1.0.0-alpha.1. Its update checks depend on the installed version:
  • A stable version receives suggestions for newer stable versions.
  • A prerelease such as 2.0.0-beta.1 receives suggestions only within that prerelease path, such as 2.0.0-beta.2. It does not suggest another channel or the stable release.
Specify the target version manually to switch channels with the previous installer. When switching to pre-built plugins, choose a stable pre-built release or publish experimental code as a custom plugin.