Spike: Building Backstage plugins using their newest Frontend architecture

[asaphko]

• Check if existing plugin code is using the latest

If we determine that we need to rewrite in a newer version of the frontend framework, we should create a new issue which details exactly what is involved in that work.

[talissoncosta]

Spike Findings: Backstage Plugin Frontend Architecture

Issue: #6359 - Spike: Building Backstage plugins using their newest Frontend architecture
Epic: #5641 - Implement Backstage Plugin
Date: December 16, 2025

---

Summary

Investigated Backstage's newest frontend architecture and compared with community plugins to determine the best path forward for the Flagsmith Backstage plugin.

---

Current State

The plugin uses the legacy frontend system (@backstage/core-plugin-api):

Package	Version	Purpose
@backstage/core-plugin-api	^1.11.1	Frontend plugin APIs (legacy)
@backstage/core-components	^0.18.2	UI components
@material-ui/core	^4.9.13	UI library (legacy)

---

Backstage Architecture Analysis

Frontend Systems

Aspect	Legacy System	New Frontend System
Plugin Definition	createPlugin()	createFrontendPlugin()
Extensions	createComponentExtension()	Blueprints (EntityContentBlueprint)
Configuration	Imperative (code)	Declarative (app-config.yaml)
Status	Stable	Alpha (recommended for new plugins)

UI Libraries

System	Package	Status
MUI v4 (Legacy)	@material-ui/core	Being phased out
Backstage UI (BUI)	CSS variables/tokens	Growing coverage

From Backstage docs:

"We maintain two parallel UI systems: Material UI (MUI) and Backstage UI (BUI)"

---

Community Plugin Comparison

Plugin	Frontend System	UI Library	Backend
LaunchDarkly	Legacy	MUI v4	Proxy only
Harness FF	Legacy	MUI v4	Proxy only
PagerDuty	Legacy	MUI v4	Proxy only
Flagsmith (ours)	Legacy	MUI v4	Backend plugin

Key Finding: All comparable feature flag plugins use:

• Legacy frontend system (not new alpha system)
• Backstage proxy (no custom backend)
• Frontend-only architecture

---

Recommendations

1. Migrate to Proxy Architecture (High Priority)

Remove backend plugin, use Backstage proxy like other plugins. Add lazy loading for performance.

Benefits:

Aspect	Before	After
Installation	2 packages (frontend + backend)	1 package (frontend only)
Initial API calls	35 (for 17 flags)	1
Configuration	Custom backend config	Standard proxy config
Pattern	Custom	Matches LaunchDarkly, Harness

Proxy Configuration:

proxy:
  endpoints:
    '/flagsmith':
      target: 'https://api.flagsmith.com/api/v1'
      headers:
        Authorization: Api-Key ${FLAGSMITH_API_TOKEN}

2. Add /alpha Export (Medium Priority)

Implement new frontend system under /alpha path for forward compatibility.

From Backstage docs:

"We recommend migrating your frontend plugins to the new frontend system. If you do please do so under an /alpha sub-path export."

Implementation:

// src/alpha.ts
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
import { EntityContentBlueprint, EntityCardBlueprint } from '@backstage/plugin-catalog-react/alpha';

const flagsTabExtension = EntityContentBlueprint.make({
  name: 'flags-tab',
  params: {
    defaultPath: '/flagsmith',
    defaultTitle: 'Feature Flags',
    filter: 'has:annotation:flagsmith.com/project-id',
    loader: () => import('./components/FlagsTab').then(m => <m.FlagsTab />),
  },
});

export default createFrontendPlugin({
  id: 'flagsmith',
  extensions: [flagsTabExtension, overviewCardExtension],
});

3. Migrate to Backstage UI (Low Priority)

Replace MUI v4 with Backstage UI components when BUI has sufficient coverage.

---

Follow-up Issues

Issue	Priority	Description
Migrate to proxy architecture	High	Remove backend, use Backstage proxy, add lazy loading
Add /alpha export	Medium	New frontend system with Blueprints
Migrate UI to BUI	Low	Replace MUI v4 with Backstage UI
Publish to NPM	High	Publish as @flagsmith/backstage-plugin
Add test coverage	Medium	Unit and integration tests

---

References

• Backstage New Frontend System
• Backstage UI Documentation
• LaunchDarkly Plugin
• Harness FF Plugin