We probably all know a developer who complains about the often frustrating developer experience within their organizations. Pain points can be a lack of service or infrastructure ownership, missing hand rails for new colleagues on the team, or the multitude of tools, dashboards, and web apps needed for maintaining and managing their projects. Mix all those factors together, and you're guaranteed to have unhappy developers knocking at your door in no time.

When the number of services, infrastructure, and projects began to rise at Spotify, they also observed these effects - and decided to act on them. Out of necessity, they created Backstage, a tool for building highly-customizable developer portals, in 2018 and donated it to the CNCF in 2020, where it's currently in an incubating state.

The Idea behind Backstage

By providing an abstraction layer for many different factors of end-to-end software development, Backstage aims to solve many problems at once:

• Context switching: By providing a single pane of glass for all services, infrastructure, 3rd party tooling, and even documentation, Backstage puts an end to dozens of browser tabs and bookmarks

• Service visibility: Developer teams get all the insights of services they have taken ownersip of, but can look for and read up on services ran by other teams in their organization as well

• Best Practices: Backstage supports developers with adhering to organization-specific guidelines and best practices by providing templates for services, software projects, and infrastructure

• Documentation: Backstage comes with means of project documentation out of the box, allowing maintainers to tie documentation closely to their projects, making it easier for others to find

Of course, developer teams will face different problems in different organizations, so this is probably not a complete list of things Backstage could do. Still, it's a comprehensive overview of its capabilities!

Catalogs, Templates, Plugins - the Architecture of Backstage

Backstage is a web application written in TypeScript, depending on a relational database and some means of caching. If you just want to spin up the standalone application on your local machine, run the following commands:

npx @backstage/create-app@latest
# wait for the installation to finish

cd <backstage_directory>
yarn dev

This will fetch and install all needed components for Backstage to run locally and start the backend and frontend services. You can now reach the web UI in your browser via http://localhost:3000. But what did Backstage actually install behind the scenes? Read on!

The Backstage Software Catalog

Backstage comes with a so-called software catalog that poses as the heart of the application - it keeps track of ownership and metadata for whichever project you tell it to, be it services, pipelines, libraries, or websites. It does so by parsing YAML files containing metadata within the projects it tracks, displaying them in the web UI and making them available for search and filter operations.

All that is needed for Backstage to track and update the metadata on-change is to point to the YAML file(s) hosted on GitHub, GitLab, or any other solution reachable by your Backstage instance. In addition, Backstage will track all so-called components created from software templates automatically (more on that in a moment).

The catalog enables developers, service owners, and maintenance teams to search for specific services, filter on configurable criteria, and distinguish between services they have taken ownership of and foreign services within their organization.

In addition, the software catalog's functionalities can be extended by adding 3rd-party plugins to Backstage, or by implementing needed functionality yourself.

Backstage Software Templates

The second core component of Backstage is called software templates, allowing teams to provide sane standards adhering to best practices for fellow developers or other teams within their organization.

Usually, Backstage would create some templated code, project configuration, and similar setup tasks while instantiating a component from a template, and push the project skeleton to a repository, e.g. on GitHub. No more creation of projects from the command line, differing between machines and workflow used by the respective team member tasked with creating it. One click from Backstage's web UI and the project is bootstrapped.

As mentioned above, components created from a template get added to the software catalog automatically, making sure that they are properly tracked by Backstage. This way, projects don't get lost or forgotten, and others will know which services exist, without you having to propagate your project to everyone within your organization.

The Backstage TechDocs

Backstage's TechDocs are another example of its usefulness as a centralized developer platform. Being Spotify's own 'docs-like-code' solution, TechDocs are Markdown files containing the project's documentation, living side-by-side with the actual codebase, just like the YAML files containing the project's metadata.

Backstage will parse the documentation and make it available next to the other information on the documented components, without any additional actions required by the developers. Due to the format being Markdown, customizing and extending Backstage's built-in support can be done by leveraging the large ecosystem revolving around Markdown, e.g. mkdocs.

Extending Backstage with Plugins

As mentioned before, Backstage is an SPA consisting of plugins, some of which build the core of the application (like templates, catalog, and TechDocs). Due to this design choice, it is very easy for organizations adopting Backstage to extend and customize the platform to their needs - after all, Backstage should be considered a platform builder, and not the finished platform.

Plugins can be written in Javascript or Typescript, and can often utilize many of the features and components Backstage provides. They will normally be routed on their own page within the web application and can do anything, from linking into the application's database to operate on data available there to integrating with 3rd-party services, SaaS offerings, or other platforms within the organization.

At the time of writing, there are 99 plugins listed on Backstage's official plugin marketplace, ranging from Lighthouse integration over CI/CD support to vulnerability scanning.

Rock the (Back-)Stage!

In conclusion, Backstage is a tool designed to centralize and streamline the developer experience within an organization. It provides a single portal for services, infrastructure, and projects, reducing context switching and increasing visibility.

By using templates and plugins, Backstage supports best practices and makes it easier for teams to adhere to guidelines, be they self-imposed or set by others. Whether you're a service owner, developer, or maintenance team, Backstage offers a comprehensive solution for managing software projects, end-to-end.

Spotify themselves put a lot of effort into the project, too - they got you covered with strategies for adopting Backstage within your organization, provide a plugin marketplace, and offer very comprehensive documentation for both, end-users and contributors.

If your organization struggles with maintaining good developer experience, project management, and service visibility, you might want to give Backstage a try! However, keep in mind, as Spotify puts it:

It might be tempting to try to optimize Backstage usage and "engagement". Even though you want to consolidate all your tooling and technical documentation in Backstage, it is important to remember that time spent in Backstage is time not spent writing code 🙃