The State of Backstage in 2025

The State of Backstage in 2025

Speakers: Avantika (Engineering Manager, Spotify), Ben (Backstage Maintainer), Frederick (Backstage Maintainer), Patrick (Backstage Maintainer), Vincenzo (Backstage Maintainer)

Conference: KubeCon EU

YouTube: https://www.youtube.com/watch?v=anqWhSnN7sA

Overview

This talk, presented by Backstage maintainers from Spotify, offers a comprehensive update on the project's significant advancements and strategic direction in 2025. Celebrating its 5th anniversary, Backstage, the open-source developer portal, has seen remarkable growth and maturity, driven by a vibrant community and continuous innovation. The presentation delves into critical project area updates, framework enhancements, and crucial insights from running Backstage at Spotify's immense scale.

The session highlights new features designed to improve developer experience, streamline maintenance, and enhance the extensibility and performance of the platform. Key themes include the evolution of the Scaffolder, the success of the community plugins monorepo, the introduction of a new design system, and major overhauls to the frontend and backend architectures. Furthermore, the Spotify team shares their battle-tested strategies for scaling the software catalog and simplifying upgrades, offering invaluable lessons for any organization adopting Backstage. This talk is essential for existing Backstage adopters, potential users, and anyone interested in the future of internal developer platforms.

Background

▶ Watch: Backstage 5-year anniversary and project overview (0:00)

Backstage originated as an internal developer portal at Spotify, designed to streamline development workflows and improve the developer experience within the company. Five years ago, Spotify open-sourced Backstage, making its powerful capabilities available to the broader tech community. Since then, it has grown into a widely adopted platform, serving as a central hub for managing microservices, documentation, and various developer tools. The project aims to solve the inherent complexity of modern software ecosystems by providing a unified interface and a robust framework for building internal developer portals.

At the time of this KubeCon EU talk, Backstage celebrated its 5-year anniversary, showcasing impressive growth metrics. The project boasts approximately 3,400 adopters, representing a 12.5% increase since the last KubeCon in Salt Lake City. The ecosystem has expanded to include roughly 230 open-source plugins, with many now consolidated within the community plugins monorepo, fostering collaboration and stability. The project's GitHub repository was nearing 30,000 stars, underscoring its widespread recognition and community engagement. This rapid adoption and continuous development highlight Backstage's critical role in addressing the challenges of developer productivity and operational efficiency in complex, distributed environments.

Key Findings

▶ Watch: Scaffolder updates: checkpoints and autocomplete (2:00)

The KubeCon EU 2025 talk on Backstage unveiled a series of significant advancements across its project areas and core frameworks, alongside critical insights from Spotify's large-scale deployment.

Project Area Updates:

• Scaffolder Enhancements: The Scaffolder now includes checkpoints for actions, ensuring idempotency and safe retries without conflicts. Additionally, autocomplete support for repository URL pickers has been introduced, streamlining the template form submission process.
• Community Plugins Monorepo Success: The community plugins monorepo has grown to 97 workspaces, a 21% increase since the last KubeCon. This monorepo model has proven highly beneficial for plugin authors, simplifying maintenance, CI/CD pipelines, and fostering better collaboration, leading to more stable and trusted plugins.
• Open API Project Area Improvements: Backstage now embeds interactive Open API documentation directly within the microsite for backend plugins, offering a Swagger-like experience. Schema testing has been implemented in-house, replacing the previous Optic tool, and future support for Open API schemas in the Scaffolder plugin is anticipated.
• New Design System (Canon): A new design system, Canon, is in early alpha. Its long-term goal is to fully replace Material UI and existing Backstage core components, providing a more opinionated, themeable, and information-dense UI library built on Base UI.
• Documentation Area Focus: Recent efforts include restructuring top-level navigation, defaulting documentation to the most recent release, and initiating work on Golden Paths—comprehensive end-to-end guides for building with Backstage's new frontend and backend systems.

Framework Updates:

• New Backend System Migration: The recommendation to migrate to the new backend system remains strong. Many plugins in the main repository no longer support the old system, and the community is encouraged to contribute to migration efforts.
• New Frontend System Evolution: Introduced roughly 1.5 years ago, the new frontend system, featuring blueprints and new APIs for extension overriding, has seen significant enhancements.
• Multiple Attachment Points: This feature allows a single extension (e.g., TechDocs add-ons) to be attached to multiple locations within the frontend extension tree, reducing duplication and complexity.
• Entity Page Improvements (Open-sourced from Spotify):
• Tab Groups: Solves the "horizontal scrolling nightmare" for instances with many plugins by grouping related tabs under a common dropdown.
• Entity Card Types / Sticky Cards: Introduces different card types, notably "sticky cards" that remain visible in the right-hand sidebar as users scroll through longer content, ideal for metadata and quick actions.
• Middleware Extension Factories: A powerful new capability allowing global modification of extensions during instantiation. Use cases include injecting debugging/analytics or enabling A/B testing by conditionally swapping or removing extensions.
• Catalog Model Extensibility: The team clarified that the Backstage catalog model is extensible, citing examples like ingesting a house inventory. Work is underway to make it significantly easier to define custom entity kinds, tweak existing ones, and establish relations between entities.

Running Backstage at Spotify Scale:

• Frontend Discovery with Gateway Instance: Spotify has open-sourced a Gateway plugin that centralizes frontend discovery for split backend deployments. Instead of hardcoding URLs or using a reverse proxy, the frontend connects to a gateway instance, which uses the discovery service to proxy requests to the correct backend plugin, simplifying infrastructure changes.
• Simplified Upgrades with Backstage Yarn Plugin: Spotify extensively uses the Backstage Yarn plugin, which resolves Backstage development dependencies based on a backstage-correct version in package.json. This dramatically reduces the lines of code changed during upgrades (e.g., from version 36 to 37, only TypeScript, Canon, and backstage-correct need bumping), minimizing friction and reducing the number of code owners pinged.
• Scaling the Software Catalog:
• Split Deployments: Spotify initially split its catalog into separate read-only and write/ingestion deployments, enabling independent autoscaling, resource allocation, and decoupled load.
• Geographical Region Splitting: Further scaling involved deploying the write API and primary database in a home region, while read APIs leverage dedicated read-only secondary databases with streaming replication across multiple geographical regions, ensuring fast, localized responses.
• Pre-production Cluster: An identical, full-fledged pre-production cluster with all data and metrics allows for safe experimentation, performance testing, and disaster recovery without impacting end-users.
• Performance Optimizations: Deep dives into OpenTelemetry and logs identified bottlenecks. Improvements include streaming large responses to prevent JSON serialization from blocking the event loop, optimizing database queries, and gracefully handling massive data dumps.
• Webhook-Triggered Catalog Updates: By leaning into GitHub webhook-triggered events, the catalog is immediately notified and reprocesses changes, significantly reducing the load from recurring processing loops on ingestion machines and the primary database.

Technical Deep Dive

▶ Watch: Community plugins monorepo growth and benefits (2:50)

Backstage's evolution in 2025 showcases a strong commitment to architectural robustness, developer ergonomics, and scalability, with several key technical components receiving significant enhancements.

The Scaffolder, a core component for creating new software components from templates, has been fortified with checkpoints. This feature ensures that scaffold actions are idempotent, meaning they can be retried safely without causing conflicts or unintended side effects. While the talk didn't delve into the precise implementation, it referenced a previous KubeCon talk for deeper technical details. This is crucial for long-running or complex scaffolding processes that might fail midway, allowing developers to resume without manual cleanup. The addition of autocomplete support for repository URLs further improves the Scaffolder's usability by suggesting existing repositories, reducing manual input errors and accelerating template form completion.

A major strategic move is the introduction of the Canon design system. This new system is built on top of an unstyled component library called Base UI, allowing the Backstage team to focus on styling, curation, and composition rather than re-implementing foundational components. The long-term vision for Canon is to entirely replace Material UI and existing Backstage core components, addressing fragmentation and providing a more opinionated, themeable library optimized for information-dense UIs. This approach aims to provide a consistent and coherent user experience across the entire Backstage ecosystem.

The migration to the new backend system remains a critical recommendation. Many plugins in the main Backstage repository now exclusively support this new system, indicating a significant shift in the project's core architecture. This new system offers improved modularity, better performance, and a more robust foundation for future development, encouraging adopters to transition to leverage these benefits and maintain compatibility.

The new frontend system, initially introduced as an alpha release approximately 1.5 years prior, has seen substantial architectural refinements. It's fundamentally structured as a tree of extensions, where each extension acts as a node with defined inputs and outputs, wired together to form the complete frontend application. A key enhancement is multiple attachment points, which addresses a common challenge where certain extensions, such as TechDocs add-ons, needed to be rendered in disparate parts of the UI (e.g., on an entity page and a TechDocs reader page). Previously, this required creating duplicate extensions or complex workarounds. With multiple attachment points, a single extension can now be declaratively attached to various locations within the extension tree, simplifying plugin development and reducing boilerplate.

Spotify's internal experience running Backstage at scale has led to several open-sourced improvements for entity pages within the new frontend system. Tab groups were introduced to combat the "horizontal scrolling nightmare" caused by over 100 plugins contributing tabs to entity pages. This feature allows related tabs to be grouped under a single dropdown, significantly improving navigation and reducing visual clutter. Furthermore, new entity card types were introduced, most notably sticky cards. These cards can be placed in the right-hand sidebar of an entity page and remain visible as the user scrolls through longer content on the left. This is particularly useful for displaying critical metadata, quick actions, or important links, ensuring essential information is always accessible.

Perhaps one of the most powerful additions to the new frontend system is middleware extension factories. This capability allows developers to globally modify extensions as they are being instantiated. This opens up a wide range of possibilities, such as injecting debugging information or analytics across all extensions without requiring individual modifications. It also enables advanced use cases like A/B testing, where extensions can be dynamically swapped out or even entirely removed based on conditions specified by the integrator. This provides unprecedented flexibility for managing and customizing Backstage applications at scale.

Spotify's migration strategy for their internal Backstage instance to the new frontend system offers a blueprint for other adopters. It employs a top-down migration approach, starting by switching out the root of the application. Conversion utilities play a crucial role, allowing existing plugin structures to be lifted into the new system. A significant recent addition is the convertLegacyAppOptions utility, which converts options from the old createApp function (like themes and sign-in pages) into modules compatible with the new system. Crucially, a new utility now picks apart existing entity page structures, converting them into separate extensions. This overcomes the previous limitation where all entity page content was forklifted as a single extension, preventing gradual migration. Now, organizations can truly migrate plugins on entity pages one by one, reducing the risk and complexity of a "big bang" migration.

Beyond the frontend, the catalog model's extensibility is being enhanced. While already extensible, the team is actively working on making it significantly easier for users to define custom entity kinds, modify existing ones, and establish complex relations between entities. This will empower organizations to represent their unique software ecosystems more accurately within Backstage.

For large-scale deployments, Spotify shared groundbreaking solutions. Their Frontend Discovery challenge, where split backend plugins need to be accessible to the frontend, was solved with an open-sourced Gateway plugin. This plugin runs on one of the backend instances. The frontend connects to this gateway, which then extracts the plugin ID from requests, uses the internal discovery service to resolve the correct backend plugin URL, and proxies the request. This eliminates the need for hardcoding URLs or complex reverse proxy rules, allowing new backend plugins to be exposed to the frontend without any infrastructure changes.

Upgrading Backstage itself, especially in large instances with many plugins and diverse code owners, can be a cumbersome process. Spotify's solution, the Backstage Yarn plugin, dramatically simplifies this. Instead of explicit version numbers for Backstage dependencies in package.json, they use backstage-correct. The Yarn plugin then resolves the correct development dependencies according to the specified Backstage version. This results in minimal changes during upgrades – for example, bumping from version 36 to 37 primarily involved updating TypeScript, the new Canon UI library, and the backstage-correct reference. This innovation has led to a significant drop in the lines of code changed during upgrades, as evidenced by a graph presented in the talk, streamlining maintenance for large organizations.

Finally, scaling the Software Catalog to nearly half a million entities at Spotify involved a multi-pronged approach. Initially, they split the catalog into two deployments: one for read traffic and another for write traffic and ingestion. This allowed for independent autoscaling and resource allocation, decoupling bursty ingestion loads from API responsiveness. Further, they implemented geographical region splitting, with the write API and primary database in a home region, and read APIs served by dedicated read-only secondary databases with streaming replication across multiple global regions. This ensures low-latency responses for users worldwide. A dedicated, identical pre-production cluster with full data and metrics was established for safe experimentation, performance tuning, and disaster recovery. Performance was further optimized through deep analysis using OpenTelemetry and logs, leading to improvements like streaming large responses to prevent JSON serialization from blocking the event loop, optimizing database queries, and ensuring graceful handling of massive data dumps from entity providers. The most impactful change, however, was transitioning to webhook-triggered events from GitHub for catalog updates. This eliminated the need for a constant, recurring processing loop, drastically reducing the load on ingestion machines and the primary database, shifting processing to an on-demand model.

Demo / Proof of Concept

▶ Watch: Documentation improvements: navigation, golden paths, builder experience (5:50)

During the talk, Ben provided a live demonstration of several key features from the new frontend system, showcasing their practical benefits.

The first feature demonstrated was the sticky card functionality on entity pages. Ben navigated to an entity page and scrolled down, illustrating how a card placed in the right-hand sidebar remained fixed and visible while the longer content on the left scrolled. This highlighted its utility for displaying essential metadata, quick actions, or important links that need to be persistently accessible to the user, regardless of their scroll position.

Next, Ben showcased the new tab grouping capability. Initially, the entity page displayed individual tabs like "Kubernetes" and "TechDocs". He then quickly edited the application's configuration by uncommenting a section of code. Upon saving, the frontend instantly updated, consolidating the "TechDocs" and "APIs" tabs into a new, single dropdown group labeled "TechDocs and APIs". This live modification effectively demonstrated how integrators can group related tabs, significantly decluttering the UI and improving navigation, especially in environments with numerous plugins.

Finally, the demo touched upon the improved developer tool experience for extensions, leveraging the new middleware extension factories. Ben opened a developer console-like view, which provided an inspector for the extensions graph. He navigated through the graph, demonstrating how developers can "dig in" to specific extensions, such as the "entity graph" extension, to view its configuration and understand its structure. This inspector offers a powerful way for developers to understand the composition of their Backstage application, debug extension interactions, and leverage the flexibility provided by middleware factories. The demo successfully confirmed that these features are not just theoretical but are actively implemented and enhance the Backstage developer and user experience.

Defensive Implications

▶ Watch: Framework updates: backend system migration encouragement (6:40)

While the talk primarily focuses on features and scalability rather than direct security vulnerabilities, the advancements in Backstage carry significant "defensive implications" in terms of best practices, operational resilience, and maintaining a robust developer experience. For organizations leveraging Backstage, adopting these new features and strategies is crucial for future-proofing their internal developer portal.

Firstly, the strong recommendation to migrate to the new backend and frontend systems is a critical defensive posture. Sticking with older systems will lead to unsupported plugins, missed features, and potential compatibility issues as the project evolves. Migrating ensures access to the latest performance improvements, security patches (though not explicitly mentioned, new systems often have a stronger security posture), and the extensible architecture needed to adapt to future demands. The new frontend system's middleware extension factories offer powerful hooks for injecting global debugging, analytics, or even security-related checks across all extensions without modifying individual plugins, enhancing observability and control.

The success of the community plugins monorepo implies a defensive benefit: plugins within this monorepo are generally more stable and trusted due to collaborative maintenance and shared CI/CD pipelines. Defenders should prioritize using plugins from this repository and consider contributing their own to benefit from community vetting and shared best practices.

Spotify's strategies for scaling the software catalog directly address operational resilience and performance, which are indirect defensive measures. Split deployments (read/write), geographical region splitting, and the use of a pre-production cluster mitigate risks associated with load spikes, regional outages, and unsafe experimentation. These architectural patterns ensure that the developer portal remains performant and available, even under heavy load or during development cycles. The transition to webhook-triggered catalog updates reduces the load on the primary database and ingestion systems, making the catalog more efficient and less prone to performance bottlenecks that could impact availability.

The Backstage Yarn plugin for simplified upgrades is a significant defensive win. By reducing the friction and complexity of upgrading Backstage, organizations are more likely to stay current with the latest versions. This means faster access to new features, performance improvements, and crucially, any security fixes that are released, thereby reducing the window of vulnerability.

Finally, the ongoing work on catalog model extensibility allows organizations to accurately model their unique software assets and relationships. A well-defined and extensible catalog is fundamental for governance, compliance, and understanding dependencies, all of which are critical for effective security and operational management within a complex microservices environment. The roadmap item for refining the configuration system also points to a defensive move, aiming to prevent configuration schema mismatches that can lead to runtime errors or unexpected behavior in plugins.

Key Takeaways

• Rapid Growth and Maturity: Backstage has achieved significant milestones in its 5th year, with 3,400 adopters (a 12.5% increase), 230 open-source plugins, and nearly 30,000 GitHub stars, demonstrating its strong community and widespread adoption.
• Enhanced Developer Experience: Core project areas like the Scaffolder have gained checkpoints for idempotent retries and autocomplete for repository URLs. The Open API project now offers embedded interactive documentation and in-house schema testing, while a new Canon design system is in development to standardize and improve the UI.
• Revolutionized Frontend Architecture: The new frontend system introduces powerful features such as multiple attachment points for extensions, tab groups to declutter entity pages, sticky cards for persistent information display, and middleware extension factories for global extension modification, significantly boosting flexibility and customizability.
• Spotify's Scaling Blueprint: Spotify has open-sourced its Gateway plugin for simplified frontend discovery with split backends and uses the Backstage Yarn plugin to dramatically reduce the complexity and lines of code changed during upgrades, offering critical solutions for large-scale deployments.
• Robust Catalog at Scale: Spotify's approach to scaling the software catalog involves split deployments (read/write), geographical region replication, a dedicated pre-production cluster, and webhook-triggered updates from GitHub, which efficiently process changes and drastically reduce database load.
• Future-Proofing and Extensibility: Ongoing work focuses on making the catalog model more easily extensible for custom entity kinds and relations, refining the configuration system, and exploring integrations like the Model Context Protocol (MCP), ensuring Backstage remains adaptable to evolving technical landscapes.

About the Speaker(s)

The talk was presented by a team of dedicated Backstage maintainers from Spotify, reflecting the project's roots and continued strong support from its creators. Avantika, an Engineering Manager at Spotify, led the introduction and provided context on Backstage's 5-year journey and growth. She was joined on stage by her Spotify colleagues, Ben, Frederick, Patrick, and Vincenzo, all of whom are also Backstage maintainers and contributed to various sections of the talk, detailing framework updates and Spotify's internal scaling solutions.

The presentation also acknowledged significant contributions from other community members and organizations, highlighting the collaborative nature of the open-source project. These included Bogdan from Bull.com for contributions to the Scaffolder, Beth and Kashish from Red Hat, and Andre from Spotify for their work on the community plugins monorepo. Aramis from DoorDash was recognized for efforts in the Open API project area and documentation, and Kristoff, a plugin maintainer, was cited for demonstrating the catalog's extensibility. This diverse group of maintainers and contributors underscores the vibrant ecosystem driving Backstage's continuous development and success.