Backstage Plugin Development 101: Introduction and a basic example
In this article we’ll cover what Backstage plugins are, how they integrate with Backstage, and show you a quick tutorial on how to develop a simple plugin.
What is backstage?
Backstage is an open source project developed by Spotify and donated to the CNCF. It has pioneered the platform engineering revolution, with internal developer platforms at the core. There are two main components to the backstage developer portal - the software catalog and the ability to deliver developer self-service actions. The goal of backstage is to organize infrastructure through the creation of the catalog, which shows everything in context - tools, data, microservices, APIs and documentation. One of the key differentiators of backstage is its flexibility, enabling the monitoring of any type of architecture and environment.
Why do plugins matter in backstage?
At the core of Backstage are the backstage plugins, that allow platform engineering teams to make backstage deliver what they need. This led to the creation of a marketplace for plugins and led to significant backstage plugin development. Recently, backstage has announced that although backstage is open sourced, five plugins will be sold through a paid subscription, pointing to where backstage believes there is extra value delivered by it.
Three plugins worth mentioning are:
- Insights, which is generally the ability to query the backstage software catalog and the ability to create reporting on top of it
- Soundcheck, which lets users create scorecards about metrics related to services and infrastructure, allowing the monitoring of metrics such as DORA metrics or production readiness.
- RBAC - role based access control which affects who sees what in backstage, and what actions can be taken depending on the users’ characteristics. This is important, with regards to the data in backstage as well as the plugins themselves.
Backstage is a plugin playground
Plugins are essentially the heart of Backstage and what makes its developer portal unique. Almost every page is a plugin, including the home page. It’s a plugin playground.
The plugin system lets you extend Backstage with features and integrations. For example, the “Todo” plugin lists TODO comments from your source code.
How plugins integrate with Backstage
To understand how plugins integrate with Backstage, we first need to understand the basic structure of Backstage. Backstage is comprised of the following:
- React Frontend, using Typescript;
- NodeJS+express Backend, using Typescript.
Plugins can extend the backend or the frontend (or both). If you want to extend the frontend you typically need to implement a React component and if you want to extend the backend you need to implement Rest API routes.
Let’s dive deeper and learn how to implement each extension:
Backstage Plugins Tutorial
First, clone backstage locally and install dependencies:
Next, we’ll use Backstage’s cli tool to scaffold an example plugin:
(when asked to enter plugin id, enter ‘my-plugin’)
The latter command creates a plugin in its own directory and integrates it into backstage. There is no black magic here, you can see the plugin under `plugins/<plugin-id>` and in order to add the plugin page to backstage’s app, the command also adds another route entry to `packages/app/src/tsx`. You can run git diff to see it for yourself:
To run Backstage and see our plugin in action, run:
Which will run both the frontend and backend of Backstage and then we can see our plugin at localhost:3000/my-plugin
The example plugin uses the random user api to display a list of users. We can learn a few things from this example:
1. Backstage comes with a core lib filled with UI components. If we open `plugins/my-plugin/src/components/ExampleComponent/ExampleComponent.tsx` We can see many UI components being imported:
2. Since backstage comes as a source code project to self host and we have access to all the code, we can essentially modify the code in any way shape or form. Because of that, it is important to follow the conventions and best practices provided by Backstage. For example, to load a plugin we use a dynamic import to keep our web app lean and fast (see plugins/my-plugin/src/plugin.ts:31
3. Again, there is no magic here, the fact that `localhost:3000/my-plugin` renders our plugin is because we added (using the backstage cli tool) the route `my-plugin` to the app’s router (`packages/app/src/App.tsx`)
To showcase how flexible Backstage is, we’ll modify the plugin to show Port inside of backstage. For the next step to succeed, make sure you are signed-up and logged-in to Port (getport.io)
First, open `plugins/my-plugin/src/components/ExampleComponent/ExampleComponent.tsx` and replace the component with the following code:
Rebuild the code by running (inside the plugin folder)
And refresh the page https://localhost:3000/my-plugin
You should be able to see Port inside of Backstage, how cool is that?
The Backstage plugin system is very flexible, but it demands managing the code by yourself and customizing internal files.
On the one hand, there is nothing you can’t do inside Backstage, but on the other hand the flexibility comes from handcrafting the app’s code, which requires coding skills and familiarity with React, NodeJS and Typescript. This makes Backstage more compatible for technical teams who are willing to code, and have the capacity and time for it, but may be cumbersome for others.
Book a demo right now to check out Port's developer portal yourself
It's a Trap - Jenkins as Self service UI
How do GitOps affect developer experience?
It's a Trap - Jenkins as Self service UI. Click her to download the eBook
Learning from CyberArk - building an internal developer platform in-house
Example JSON block
Core Kafka Library
Core Payment Library
Cart Service JSON
Products Service JSON
Scaffold a new microservice
Deploy (canary or blue-green)
Force merge pull request (skip tests on crises)
Add environment variable to service
Add IaC to the service
Upgrade package version
Spin up a developer environment for 5 days
ETL mock data to environment
Invite developer to the environment
Extend TTL by 3 days
Provision a cloud resource
Modify a cloud resource
Get permissions to access cloud resource
Update pod count
Update auto-scaling group
Execute incident response runbook automation
Add / Remove / Update Column to table
Run Airflow DAG
Change customer configuration
Update customer software version
Upgrade - Downgrade plan tier
Create - Delete customer
Machine learning actions
A/B testing traffic route
Spin up remote Jupyter notebook
Containers & Serverless
Software and more