IDP with Backstage: 7 pitfalls to avoid

This article was originaly written in french for sfeir.dev. Original version can be found here

Backstage is an open-source framework dedicated to building Developer Portals. Developed and maintained by Spotify, the project is now part of the CNCF (Cloud Native Computing Foundation). Since its launch in 2020, the project has grown considerably: over 1,650 contributors, nearly 30k stars on GitHub, and even a dedicated conference day — BackstageCon — alongside prestigious events like KubeCon and CloudNativeCon. The framework has become a go-to option for any organization looking to build a Developer Portal. However, implementing Backstage can turn out to be very frustrating if you don’t watch out for the pitfalls along the way.

Not Thinking About an Adoption Strategy

Let’s start by talking about strategy — specifically the one dedicated to adoption of your portal by your teams.

This is one of the first pages of the Backstage documentation you should read before even getting started. One of your primary goals when building a Developer Portal is to ensure it gets adopted by everyone. If it doesn’t, you will have just wasted a lot of time and money.

The team responsible for integrating Backstage — or more broadly, the platform — will need to drive change management. As Spotify describes it, if your “customers” (i.e., the development teams) don’t feel included and heard, you’ll likely fail to co-build your portal with them. Workshops, pair/mob programming, tutorials, demos, metrics, and other techniques will be your allies.

Trying to Do Everything at Once

In a Platform Engineering approach, the path to a stable and functional platform is long. From gathering requirements to going live and iterating on feedback, it takes time to implement the right solutions. A Developer Portal is almost just the cherry on top of the Platform Engineering cake. The biggest part of the added value of your platform lies in the services it provides; the portal is only there to expose them in a simple and intuitive way. Of course, some elements may only belong in the portal itself, such as displaying metrics.

In my experience, it’s risky to simultaneously launch the development of platform services AND your portal. Depending on your team’s configuration and maturity, you risk constantly waiting on either the front end or the back end to make progress. You may also lose time when gathering feedback on your services. If the back-end/platform features don’t meet expectations, you’ll likely need to modify the front-end/Backstage as well. There are many other ways to expose your services than a front end, especially if your customers are mostly developers. A CLI or an API will work just fine in the early stages.

If you’re familiar with the terms Day-0, Day-1, and Day-2 to describe a software lifecycle, the portal should arrive at the “Day-2” stage of your platform’s lifecycle. I had the chance to talk about this in a presentation/REX talk at Devfest Nantes 2024: Platform Engineering Day-2: Unify your tools with Backstage

Hidden Costs

Another thing to consider before using Backstage is the technical stack the framework imposes. You will have no choice but to use React as an SPA for the front end and Express.js for the back end.

Depending on the skills available to you, and for a project this foundational, expect additional recruitment costs for an experienced team. Developers familiar with other frameworks can work on Backstage, but it’s preferable to have at least one React expert to avoid having to rethink everything a year down the line.

Linking back to the previous pitfall: if you hire a team but they can’t be effective because you’re trying to do everything at once, you will inevitably lose money.

Reinventing the Wheel

One of the biggest advantages of Backstage is its open-source nature. With over 1,650 contributors, the Backstage ecosystem is a goldmine for those who know how to leverage it. The plugins page on the Backstage website lists over 230 plugins, only 5 of which are not community-contributed.

Before developing your own internal plugin to integrate one of your tools, it’s worth taking a look at the plugin list. This is where Backstage’s core value lies — you can experiment and get feedback very quickly. Of course, you won’t reach your final goals in a week, and you’ll likely need to develop custom features and plugins. However, it would be a shame not to take advantage of a very short feedback loop that will help you refine your needs and address them better over time.

That said, be careful with open-source plugins — make sure they are maintained and up to date!

Fighting the Framework

This pitfall shares the same spirit as reinventing the wheel. If you choose to use Backstage, you will be constrained to use its technologies and abide by its choices. You can’t use a framework other than React, can’t drop Express.js, can’t integrate your own Design System, and the list goes on… I’m deliberately overstating the point, because in practice you could try to do all of this and might even succeed — but you would waste a lot of time and money fighting a framework that doesn’t suit you.

When this behavior appears, you need to ask the right questions. If you’re at an advanced stage of your Developer Portal usage, perhaps it’s time to move away from Backstage toward a solution that suits you better — and that’s perfectly normal. On the other hand, if this behavior appears from the very beginning, there are two possible scenarios:

• Backstage is not suited to your needs/context
• Your needs are not as specific as you think

It can be difficult to identify which scenario you’re in. You need to step back and sometimes make compromises. Backstage is a great tool for iterating quickly — use it as such, and don’t impose unnecessary complexity on yourself by moving too fast toward something too specific.

Not Building Plugins

I mentioned earlier the importance of exploring community plugins, because the plugin system is at the heart of Backstage. All the features that come out of the box with Backstage are actually plugins themselves. This means you’ll need to segment your features into small, independent “modules” that you can then integrate using the APIs provided by Backstage. You could code everything in the main application and overload Backstage’s front end, but I wouldn’t recommend it for several reasons.

As mentioned earlier, if you ever want to move away from Backstage in the future, you’ll have a hard time extracting your features. Similar in spirit to hexagonal architecture — though to a lesser degree — the plugin system allows you to isolate your features. Feature isolation also makes testing easier.

This isolation through plugins will also prevent you from “polluting” one concept with another, avoiding a “big ball of mud”. By default, each plugin has its own database, which further limits the temptation to mix everything together.

Skipping Inner-Source

This is mentioned in the Backstage documentation: team collaboration and inner-source are key success factors for a Developer Portal built with Backstage. Beyond benefiting from community plugins, you should also take advantage of your internal community and what it can bring you.

The scope covered by a good Developer Portal is too vast to be managed effectively by a single person. So why not leverage the expertise of your users to help you build the best possible solution?

The plugin system is also designed with this use case in mind. For example, if a team wants to find information in your portal about a tool that’s essential to them but not to the majority of the company, it probably won’t be your priority. But if that team can autonomously address that need, then everyone wins. Of course, this kind of organization and contribution model requires setting clear guidelines and rules to remain in control of the application.

Bonus: Lessons Learned

The first thing to do before using a framework like Backstage is to take stock of your existing IT landscape. You may not realize it, but you might already have some independent building blocks that would have a natural place in a Developer Portal. It all depends on the maturity of your IT systems and how far along you are in your Platform Engineering journey. To identify them, you need to know what goal you want to achieve through the implementation and use of a Developer Portal. If that target vision overlaps with the individual initiatives led by your teams, there may be something worth exploring.

Recently, I accompanied a client in their desire to integrate Backstage into their IT landscape, and we quickly ran into this reality. This client was already at a relatively advanced stage in their Platform Engineering journey but wanted to go even further.

An initial set of needs had been identified and work to address them had begun. Some time after I joined, with a clearer understanding of the chosen direction, it quickly became obvious that something was going to clash: the tools already in place. Many internally developed tools were already deployed and working well. These tools were used by hundreds of engineers and dozens of teams. There was a strong adoption rate and teams could hardly do without them. That said, there were still things to improve — and that was the rationale behind the desire to use Backstage and develop new services.

What strategy should be adopted in this situation?

Tools are already in place, the teams administering and developing them have become domain experts, the services they provide ease users’ lives and reduce cognitive load, users are happy with the available services (though room for improvement exists) and show a high engagement rate… Perhaps this is a sign that the battle should not be fought through Backstage but through the evolution of the existing tools, toward a more unified approach (similar to what Backstage advocates, but without having to start from scratch).

Conclusion

Backstage is a great framework when you use it for the right reasons. If you’re at the beginning of your Platform Engineering journey, starting with the Developer Portal may not be the best entry point. Focus on what brings value. Once the unknowns are cleared, you’ll be more confident when integrating your portal.

Once you’ve started working with Backstage, make the most of the ecosystem it offers. Explore community plugins, build your own plugins, contribute to improving Backstage through open source, and include your teams in co-building your portal.

Finally, beware of the hype effect (sometimes called Hype Driven Development) and Cargo Cult thinking. Don’t rush headlong into Backstage — take a step back and determine first whether the framework can meet your needs.