Switching to pre-built plugins

Portal’s previous plugin installer installed plugins from npm packages and ran a build whenever you installed, updated, or uninstalled a plugin. It handled both public packages and your organization’s private packages, which you published to the Portal package registry. Portal is replacing that installer with two approaches:

• Pre-built plugins are supported public plugins that Spotify builds and prepares in advance. You choose and install their prepared releases from Plugin Settings.
• Custom plugins are plugins your organization develops, modifies, or maintains. You build and publish them from a Backstage workspace directly to a publishing source in your Portal instance using the Portal CLI.

These approaches are being rolled out to Portal instances throughout September 2026. Both let Portal load plugins that have already been built, removing the installation-time build step. Existing plugins installed with the previous installer need to move to one of these approaches. This guide explains what changes and how to activate and test replacements before removing the previous installations.

​

What changes

You still use Plugin Settings to explore, install, update, and uninstall public plugins. Installation adds an Analyze step where you review the resolved package versions and related frontend, backend, and module packages before confirming. For plugins your organization develops or maintains, publishing also changes. Instead of publishing individual npm packages to the Portal registry, you build and upload a workspace release with the Portal CLI. A publishing source groups the workspace’s plugins into one release, and source-scoped tokens let you publish from local development or CI/CD. Use Studio to test the workspace before publishing. Pre-built installation supports stable versions and latest. To use experimental or prerelease code, publish it as a custom plugin. See Plugin Versioning for the version and revision update behavior. Plugin-specific configuration and testing remain necessary with both types of plugin.

​

Availability

During the September 2026 rollout, availability may differ between instances. The Custom Plugins tab under Admin → Plugin Settings indicates that the new approaches are available in your instance. Until then, use the Using the previous installer instructions at the bottom of the installation, updating, uninstalling, and versioning pages. Existing packages need to be moved even after your instance has the new experience. The steps below let you activate and test replacements before removing the previous copies.

​

Before you migrate

Before starting, consider how you will verify that your plugins still work as expected after migration. If you have many plugins, consider migrating in stages so you can verify each group before moving on to the next. The Installed tab displays migration notices after Portal has compared legacy package names with the pre-built plugin catalog:

• Move packages to pre-built installs lists public packages with a prepared release that Portal can install directly.
• Move custom plugin packages lists packages that are not in the pre-built catalog and need to be published from your own workspace.
• Packages shown as Not ready yet are known, but do not currently have a release that Portal can install.

Migrate related frontend, backend, and module packages together whenever possible.

​

Migrate to pre-built plugins

1. Go to Admin → Plugin Settings.
2. In the Move packages to pre-built installs notice, select Review pre-built migration.
3. Review the packages Portal resolved. Select the plugins and modules you want to move.
4. Select Switch to pre-built.
5. Wait for the operation to finish, then verify each replacement. Plugins that were running remain running after a successful switch; stopped plugins and modules remain stopped.

Portal installs the prepared replacement first and leaves the legacy copy installed. The replacement takes precedence at runtime, which lets you test it before cleanup. Do not remove the legacy copy yet. If a package appears under Not ready yet, read the reason shown in the dialog. Check the plugin release for a metadata, compatibility, dependency, or build problem and look for a newer version. If the reason is unclear, contact Customer Support with the package name, Portal instance, and message. For experimental code, follow the custom publishing guidance.

​

Migrate to custom plugins

Packages in the Move custom plugin packages notice are not available as pre-built plugins. They are typically private or organization-specific packages that were previously published to a package registry and installed from there.

1. In the notice, select Review custom migration and record every package listed.
2. Find the source repository and Backstage workspace that produce those packages. Stop publishing new releases through the previous Portal package registry flow.
3. Make sure the packages use the new frontend or backend system and have valid Backstage package metadata. Use Portal Studio to update and test them if needed.
4. Create a publishing source for each workspace under Admin → Plugin Settings → Custom Plugins. Use one source for the whole workspace rather than one source per package.
5. Create a source-scoped publishing token and add portal-cli repo publish to the workspace’s CI/CD release flow. See Publish and install custom plugins for the complete setup and an example pipeline.
6. Publish a source version containing all of the packages listed for that workspace. Preserve the package names and plugin IDs so Portal can match the replacements to their legacy copies.
7. Confirm that the new source version is active. Start any replacement that should be running, then verify its behavior and configuration.

Repeat these steps for each workspace represented by the migration list. If the original source code or ownership of a package is unknown, resolve that before migration; the previous installed artifact is not a maintainable substitute for a source workspace.

​

Verify the replacements

Before cleanup, check that the migrated plugins still work as expected for the features your teams use. If a pre-built replacement does not work as expected and shows Legacy copy installed, you can revert by uninstalling the plugin. This removes the pre-built version and restores the previously installed copy. This option is only available before you remove that copy during cleanup. If you need help, collect the package version and visible error details before contacting Support. If a custom release fails, pin its source to the previous known-good version while you fix and republish the workspace. If an individual custom plugin does not work as expected, consider republishing the workspace without it using --exclude-plugin or --exclude. This lets you keep the other custom plugins active and continue validating them while you fix the affected plugin, without removing the entire publishing source. See Select what to publish for examples. Make sure the new source version is active, and leave the affected plugin’s previous installation in place until its replacement is working.

​

Remove previous installations

After Portal detects a migrated package alongside its previous installation, the Clean up legacy plugin copies notice appears on Plugin Settings.

1. Confirm again that every selected replacement works correctly.
2. Select Review cleanup.
3. Review the selected legacy copies. Clear any plugin that you are not ready to remove.
4. Select Uninstall legacy copies.
5. Monitor the cleanup build until it completes, then run a final check of the replacement plugins.