Skip to main content

Get started

Getting started with plugins​

Plugins, in both Portal and Backstage, are composed of npm packages. A plugin can have one or more packages. A plugin might have a package for the frontend React code, a package for the backend Node API code, and other packages for sharing code between the two. This follows the package structure encouraged by Backstage.

Backstage has certain ways to hook in functionality through its frontend and backend plugin systems. This typically means that plugins need to have certain exports defined. For example, backend plugins will typically export the output of createBackendPlugin, a utility included in Backstage applications.

In addition to regular plugins, Portal and Backstage also support modules. A module is a npm package that extends the functionality of another plugin, such as the software catalog or Soundcheck. Modules are different from plugins in that they must be installed alongside the plugin that they extend. Modules use extension points offered by other plugins.

This section walks through the basics of creating a custom plugin for Portal: setting up your environment, creating a Backstage application, and creating and testing the plugin.

Before you begin​

Portal and Backstage use Node (a JavaScript runtime) and Yarn (a JavaScript package manager) for development. These tools must first be installed on your machine for plugin development.

  1. Verify that node is installed and is a version supported by Backstage. If needed, follow the instructions on nodejs.org to install Node.
$ node --version
  1. Verify that Yarn is installed and is a version supported by Backstage. If needed, follow the instructions on yarnpkg.com to install Yarn.
$ yarn -v

1. Create & run a Backstage application​

Portal and Backstage plugins are published independently, but run as part of a Backstage application. To make it easy to develop and test a plugin, we advise creating a monorepo that contains a sample Backstage application and your plugin.

  1. Create your Backstage application:
$ npx @backstage/create-app
  1. Change into the application directory that you created:
$ cd my-backstage-app # your app name
  1. Run the application to ensure that it starts up:
$ yarn dev # ctrl-c to stop

Within the application directory, there are top-level folders of packages and plugins. The packages directory contains code relevant to the Backstage application; inside this folder are app (frontend) and backend (backend) packages. The plugins directory is where new plugins that you create will be added.

2. Create your plugin​

To create a plugin, you’ll use a Backstage tool called backstage-cli. This is the command-line tool for Backstage applications. It’s used to build, test, and package plugins.

  1. Create your plugin:
$ yarn backstage-cli new

The new command creates a new plugin. This will launch an interactive prompt to help create the plugin. The first question asks what kind of plugin you’d like to create. The options correspond to package roles that Backstage recognizes.

The most applicable types early on are plugin (for a frontend package) or backend-plugin (for a backend package). There’s also an option for backend-module, which you can use if you intend to create a catalog module or Soundcheck module, for example.

From this point, plugin development is an open box. Backend plugins can follow this guide; frontend plugins can follow this guide. Frontend plugins will likely want to use extension blueprints to create pages, sidebar items, or other content.

Plugin requirements for Portal​

Portal exclusively uses the new frontend and new backend systems in Backstage. The new backend system is the default when creating backend plugins; the new frontend system is still in alpha and therefore not yet the default when creating frontend plugins. Frontend plugins that you create should follow the migration guide to create an alpha export that Portal can use.

If you have any issues getting set up, see the Backstage getting started documentation.

Migrating existing Backstage plugins to Portal​

Portal is built on Backstage, so any Backstage plugin can work in Portal; however, many will need a minor migration to match up with the requirements for Portal. This guide will show you how to migrate your existing Backstage plugin to be Portal compatible.

As mentioned earlier, Portal exclusively uses the new frontend and new backend systems in Backstage. The main migration needed for existing plugins is typically to move the frontend plugin to the new frontend system. Getting ahead of this migration is recommended because Backstage will soon deprecate the older systems.

Portal is published as a Docker image, so it is possible to develop plugins directly with Portal. However, the Docker image expects compiled packages and does not yet support hot reloading, which slows the development cycle. For now, we recommend developing your plugin using an open-source Backstage application. Plugins can be published and installed in Portal later in development, to fully test your changes.

note

Currently, only backend plugins are supported as the new backend system is stable. While frontend plugins can be migrated, the new frontend system is still unstable. Please note that migrating frontend plugins now will likely require additional updates as the system becomes stable and generally available.

Before you begin​

Verify you’ve set up a Backstage application locally. See the getting started section for more information.

1. Migrate to the new frontend & backend systems​

The Backstage open-source project has recently introduced new versions of the frontend and backend system. Not only do these new systems improve the experience of maintaining and installing plugins in Backstage applications, they also power the in-product plugin experience in Portal.

  • Migrate your frontend plugin to the new frontend system (link)
  • Migrate your backend plugin to the new backend system (link)

2. (Frontend) Ensure the plugin uses theme variables​

Portal applies a global theme to create a consistent, cohesive user experience. For an existing plugin to work seamlessly in Portal, frontend elements should use variables from the Backstage theme, rather than hard-coded colors or spacings.

You can test the theming by installing your plugin to Portal (Step 6).

Ensure your plugin matches the Backstage Component Design Guidelines as closely as possible, namely:

  • Using Backstage components wherever possible (Storybook), and otherwise falling back to Material UI components (Material UI docs).
  • Any custom CSS in your frontend code should use theme variables such as colors and spacings rather than using static values, to ensure the styling is correctly overridden by the custom Portal theme.

For a quick test, you can also try out your plugin in the default light and dark themes included with an open-source Backstage application.

3. Publish plugin to registry​

Once you feel your plugin is ready, you can publish it to a registry before we can install it in Portal.

4. Install a plugin in Portal​

Sample plugins​

Here are a few reference examples of plugins that have been recently migrated to be Portal compatible.