Developer portals provide important information and tools for prospective developers. This includes documentation, code samples, and other resources to help developers build applications. A company might create a developer portal to promote its API-as-product, or an individual might generate one to share their knowledge and expertise.

Backstage is an open-source software catalog and developer platform designed and developed by Spotify that enables organizations to manage their software development process more effectively. It provides a centralized repository for software development assets, such as code, documentation, and tools, and makes it easy for developers to search for and reuse these assets. In addition, Backstage provides a suite of tools to help developers collaborate more effectively, such as a project management system, a code review tool, and continuous integration solutions. At the time of writing, Backstage is an incubating project within the Cloud-Native Computing Foundation (CNCF).

Below, we’ll briefly walk through using Backstage, specifically to generate developer portals. We’ll outline the benefits of creating an API developer portal and see just how easy it is to set one up using Backstage.

Benefits of Offering a Developer Portal

First off, what are the benefits of building a developer portal? Well, a developer portal can help you market your API to developers with a self-service platform to get started. Valuable resources and documentation can help developers get started quickly and easily. It’s also key to keeping existing developers up-to-date on changes and new features.

As a result, a developer portal is critical to driving the adoption of an API or software product. By providing an easy way for developers to get started, you can reduce the barriers to entry and make it more likely that developers will use your API or product. Additionally, a developer portal can help build relationships with developers by providing a central resource for information and support.

Creating a Developer Portal With Backstage

There are many potential benefits to building a developer portal using Backstage. First, it gives developers a single place to go to find all the information they need about your platform. This can include documentation, code samples, tutorials, and more.

Second, it makes it easy for developers to get started with your platform. They can sign up for an account, create a new project, and get started right away. Third, it provides a way for developers to stay up-to-date on what’s going on with your platform. They can see new features and updates and get notified when something changes that might affect their development.

Lastly, it allows you to track and manage your development community. You can see who is using your platform, what they’re working on, and how they’re doing.

Prerequisites

• NodeJS installed

Installing Backstage

To install Backstage, use the following command:

npm install @backstage/create-app
npx @backstage/create-app

You should see the below line in the terminal where you need to enter a name for your app. For instance, we’ll use test-app:

Once done, run the app using the following command:

cd test-app
yarn dev

Then go to https://localhost:3000, and you should see the below Backstage demo page that is called Catalog.

Configuring the Developer Portal in Backstage

Integrate GitHub Into the Backstage App

To integrate GitHub into the app, go to the Backstage app directory and then open the app-config.yaml in the code editor and replace the integrations section with the following code:

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

Note: You have to add your GitHub token here and restart the server. You can check out the steps here to get the Personal Access Token for Github.

Creating the Documentation Template

To start creating a documentation template, do the following:

• Go to the create components section
• Select choose in the document template
• Fill in all the info asked
• Select create

Now you will see that it created a new repository in your GitHub profile with the name of “Documentation” and also created the new doc in the document section of the backstage app.

Final Words

Backstage gives you an open platform for building a developer portal. A lot of work is involved in creating each module/section — therefore, a helpful tool can save precious time. Using Backstage, one can add components and then link them together. You can set ownership, change all sorts of metadata, like the modules or section names, as well as add other interesting components to your workspace while customizing the look and feel.

If you need to gather technical information on different related software components, consider giving Backstage a try. It’s certainly not the only option for this task, but it’s a popular choice for particular use cases.

We hope this blog post has shared some of the things we learned from our experience using Backstage. If you have any other questions feel free to comment down below.