Skip to main content

Developing Plugins for Portal

Portal is based on Backstage, so many plugins developed for Backstage are already compatible with Portal.

Portal requires that plugins use the new backend and new frontend systems. Plugins that do not yet support these new systems are not compatible with Portal.

To develop your own plugins, we suggest local development using a standard Backstage app created with npx @backstage/create-app. This is most convenient, as it doesn't require a Portal license key.

Portal has a custom theme from Spotify. Plugin authors should be careful to test plugins with the default Backstage light and dark themes, to ensure that colors from the theme palette are used. Lack of support for the new frontend or backend systems and theming issues are the main sources of incompatibility with Portal.

Portal Cloud​

Portal Cloud is the cloud-based, software-as-a-service (SaaS) version of Portal hosted by Spotify. Portal Cloud supports installing community or custom plugins, with the same requirements mentioned above.

Publishing plugins to Portal Cloud​

To publish a plugin to Portal Cloud, contact Spotify to receive a publishing token for your Portal Cloud instance.

Next, set up your local environment to publish to your Portal Cloud instance:

  1. Configure your plugin's package.json to add a registry key:
{
  "name": "@portal-internal/plugin-example",
  "version": "0.1.0",
  ...
  "publishConfig": {
    "registry": "https://<company>.spotifyportal.com/api/plugin-installer/registry/npm"
  },
  ...
}
  1. Add a .yarnrc.yml with the npmAuthToken key defined with an environment variable:
npmAuthToken: ${PORTAL_PUBLISHING_TOKEN}
  1. Export the publishing token you received from Spotify:
export PORTAL_PUBLISHING_TOKEN=<token>
  1. Build your plugin:
# From a monorepo root directory
yarn tsc && yarn build:all

# From the plugin directory
yarn tsc && yarn build
  1. Publish your plugin:
# From a monorepo root directory
yarn workspace @portal-internal/plugin-example npm publish

# From the plugin directory
yarn npm publish
  1. Repeat step (5) for any other plugin packages (e.g. backend or common packages).

When publishing subsequent versions, be sure to increment the version field in your package.json file. This can be done manually, or with a change management tool like changesets.

Installing plugins in Portal Cloud​

After publishing your plugin, it can be installed from the Config Manager in Portal. When signed in as an authorized user, click Add Plugin and enter the npm package name of your plugin. Enter additional package names if your plugin has multiple packages (e.g. a frontend and a backend package).

From this point on, the installation, configuration, upgrade, and uninstallation of your plugin works the same as any community or third-party packages installed in Portal.