Enable javascript in your browser for better experience. Need to know to enable it? Go here.
Backstage: The Developer Portal that organizations need for their developers

Backstage: The Developer Portal that organizations need for their developers

As part of the process of creating software, digital products, among others, where multiple teams, people, roles and processes are involved within an organization, sharing information and knowledge is becoming increasingly complex and even unmanageable.


For example, each team within an organization has its own sources of information (documentation, apps, code, processes) and there is no way to know how the organizations or companies are formed, which manage several lines of business, with different teams, there is no information on who are the current leaders, team members are constantly rotating or leaving the organization, there is no updated organizational structure of all this information that is constantly changing, it does not allow people or systems to be points of reference or contact for information. 


We must also consider the change of context, fragmented systems, onboarding processes and outdated documentation; all these circumstances awakened the need to create a platform that solves this problem. This is how Backstage, developed by Spotify, was born. 


What is Backstage?


Backstage works as a "platform of platforms", any team/individual within an organization can contribute to this platform, the core team (in charge of Backstage) must treat these contributing teams as customers of the platform. Code collaboration can be incentivized using tools like Github. These code contribution techniques are taken from the InnerSource, which contains open source development fundamentals and practices that can be implemented within an organization.


Backstage has a very active community, which is always ready to answer doubts or questions, they meet frequently to share news, new developments, improvements issues detected to encourage developers to contribute code.


How to measure impact (KPIs and metrics)


These are some of the metrics that can be used to verify if Backstage has a successful impact on the software development process within an organization:


  • Onboarding time

  • Offboarding time

  • Number of PRs that have been merged per developer/day/team

  • Deploys to production

  • Context switching (Different initiatives a team is working on)


If you want to learn more about practices for Backstage adoption, this Spotify article recommends some best practices.


Core Features


          1.  Software Catalog

It makes it possible for a single team to manage dozens of software components and for your organization to manage thousands of them, allowing teams to visualize projects and dependencies. 


Instead of using the console of a cloud service provider, such as AWS or GCP, you can integrate the option to manage the lifecycle of a component within Backstage.


          2.  Software Template

It makes it easy for developers to create a new microservice, mobile feature, pipeline or any other software component; it allows to automate processes such as onboarding and offboarding. 


The time for a Walking Skeleton is reduced to a few clicks, so software developers can focus on creating features. A successful case of onboarding within Spotify is the use of Golden Paths as part of the onboarding process. The concept of Golden Paths translates: to the "determined and supported" path to "build something" (e.g., create a back-end service, install a website, create a pipeline). The Golden Path tutorial is a step-by-step tutorial that guides you through this path with feedback and support.


          3.  Kubernetes Integration

It is a tool designed around the needs of service owners, rather than cluster admins. Developers can easily check the status of their services no matter how or where those services are deployed, whether on a local host for testing or in production with dozens of clusters across the organization.


         4.  Backstage Search

When you have thousands of developers building thousands of components, how can anyone find anything? Backstage allows you to find service owners, components and documentation. 


New developers can find information, everyone can share, create and collaborate together, avoiding duplication of effort, because everything can be found within one place in Backstage.

         5.  TechDocs

This is Spotify's own docs-like-code solution built into Backstage. This means that developers write their documentation in Markdown files that live alongside their code. This makes it easy for developers to avoid having to use another tool for documentation.


Install Backstage locally


For the backstage installation, I have left a detailed step-by-step on how to do it, in order to facilitate the process. 



  • yarn >= 1.22.17

  • node >= 14.17.0


Tech stack:

  • React

  • React Testing Library

  • Typescript

  • Javascript

  • Express

  • Cypress

  • Lerna

  • Docker




Install Backstage as Single Page Application (SPA):

npx @backstage/create-app

Install dependencies:

yarn install

To lift locally, inside the packages/app directory run:

yarn dev



Backstage is a platform that allows solving many problems within an organization: finding information and documentation from different teams; creation and management of components from a single place; code contribution, all this allows breaking silos between teams. Silos affect productivity because teams or different business areas act in isolation, making decisions where systems and team members do not communicate with each other.


If you want to know more about this interesting platform, I recommend you to start exploring it and if you are interested in open source development, you can contribute to the development of features or code improvements.

Disclaimer: The statements and opinions expressed in this article are those of the author(s) and do not necessarily reflect the positions of Thoughtworks.

Do you want to be part of our team?