fix(backend-dynamic-feature-service): fall back to main from alpha by gashcrumb · Pull Request #34535 · backstage/backstage

gashcrumb · 2026-06-10T13:33:57Z

Hey, I just made a Pull Request!

Dynamic backend plugins with an alpha package.json failed to load when the alpha export only exposed supplementary APIs, even if the main export was valid. The loader now tries the alpha entry first and falls back to the main export when no valid plugin installer is found.

Without this fix, attempting to load plugins such as catalog-backend using the backend dynamic feature service will currently fail with an error similar to following message:

dynamic backend plugin '@backstage/plugin-catalog-backend-dynamic' could not be loaded from 'file:///opt/app-root/src/dynamic-plugins-root/backstage-plugin-catalog-backend/alpha': the module should either export a 'BackendFeature' or 'BackendFeatureFactory' as default export, or export a 'const dynamicPluginInstaller: BackendDynamicPluginInstaller' field as dynamic loading entrypoint.

Assisted-By: Cursor Desktop

✔️ Checklist

A changeset describing the change and affected packages. (more info)
Added or updated documentation
Tests for new functionality and regression tests for bug fixes
Screenshots attached (for UI changes)
All your commits have a Signed-off-by line in the message. (more info)

backstage-goalie · 2026-06-10T13:34:27Z

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@backstage/backend-dynamic-feature-service	packages/backend-dynamic-feature-service	patch	`v0.8.3-next.0`

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Fixes dynamic backend plugin loading so that when an alpha package.json exists but doesn’t expose a dynamic plugin entrypoint, the loader falls back to the main package export instead of marking the plugin as failed.

Changes:

Refactors plugin loading to try multiple entrypoints (alpha first, then main) and resolves installers via a helper.
Adds unit + integration coverage for the alpha-fallback behavior.
Adds a fixture dynamic plugin that has an alpha export with only supplementary APIs plus a changeset entry.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/backend-dynamic-feature-service/src/manager/plugin-manager.ts	Implements “try alpha then main” entrypoint loading and factors installer resolution into helpers.
packages/backend-dynamic-feature-service/src/manager/plugin-manager.test.ts	Adds a unit test ensuring fallback to main when alpha doesn’t provide an entrypoint.
packages/backend-dynamic-feature-service/src/features/features.test.ts	Adds an integration test validating fallback behavior and associated logs/scanned package metadata.
packages/backend-dynamic-feature-service/src/features/fixtures/dynamic-plugins-root-for-alpha-fallback/test-backend-alpha-fallback-dynamic/package.json	Adds fixture plugin package manifest with main + alpha export mappings.
packages/backend-dynamic-feature-service/src/features/fixtures/dynamic-plugins-root-for-alpha-fallback/test-backend-alpha-fallback-dynamic/dist/index.cjs.js	Fixture main entry exporting a backend plugin.
packages/backend-dynamic-feature-service/src/features/fixtures/dynamic-plugins-root-for-alpha-fallback/test-backend-alpha-fallback-dynamic/dist/alpha.cjs.js	Fixture alpha entry exporting only supplementary APIs (no installer).
packages/backend-dynamic-feature-service/src/features/fixtures/dynamic-plugins-root-for-alpha-fallback/test-backend-alpha-fallback-dynamic/alpha/package.json	Fixture alpha package.json pointing at the alpha bundle.
.changeset/fix-dynamic-plugin-alpha-fallback.md	Documents the patch fix and expected loader behavior.

Dynamic backend plugins with an alpha package.json failed to load when the alpha export only exposed supplementary APIs, even if the main export was valid. The loader now tries the alpha entry first and falls back to the main export when no valid plugin installer is found. Signed-off-by: Stan Lewis <gashcrumb@gmail.com> Assisted-By: Cursor Desktop

Copilot

Pull request overview

Copilot reviewed 6 out of 8 changed files in this pull request and generated no new comments.

schultzp2020

🛶

This change adds a temporary patch to update the backend dynamic feature service so that it will also load backend plugins that have an alpha export but do not export the plugin object in that alpha export. The patch is similar to the fix applied in this PR: backstage/backstage#34535 Assisted-By: Cursor Desktop

freben

Alright, since this is a valuable fix let's merge this with some comments for potential follow-up cleanup. I think it's correct at runtime, which is what's most important.

freben · 2026-06-16T11:04:15Z

+      },
+    ];
+
+    if (entryPoints.length === 0) {


This can actually never happen now

freben · 2026-06-16T11:04:45Z

-      if (dynamicPlugin.installer) {
+    const entryPoints: Array<{ location: URL; manifest: string }> = [
+      ...(plugin.alphaManifest?.main
+        ? [


This could have looked clearer with an if and a push, instead of the ternary+spread

freben · 2026-06-16T11:06:53Z

      return dynamicPlugin;
    }
+
+    return dynamicPlugin;


I don't think this can technically happen now either, right? The code above seems to always do either continue or throw.

freben · 2026-06-16T11:09:29Z

+): Promise<{
+  installer?: BackendDynamicPlugin['installer'];
+  error?: Error;
+}> {


This could have been a discriminated union if we wanted some extra clarity

freben · 2026-06-16T11:13:40Z

+      }
+
+      if (!loadResult.error && index < entryPoints.length - 1) {
+        continue;


Perhaps a matter of taste, but continue is a bit of a minor smell that can often be rewritten more readably. I think in this case it shadows the fact that the final return can't happen for example.

The overall structure could probably have been

let outcome = load(first); if (condition && second) { outcome = load(second); } if (outcome is error) ... return

github-actions · 2026-06-16T11:16:27Z

Thank you for contributing to Backstage! The changes in this pull request will be part of the 1.52.0 release, scheduled for Tue, 16 Jun 2026.

gashcrumb · 2026-06-16T11:40:49Z

Alright, since this is a valuable fix let's merge this with some comments for potential follow-up cleanup. I think it's correct at runtime, which is what's most important.

@freben Sounds good! I'll prepare an update that incorporates your feedback, thanks!

This change adds a temporary patch to update the backend dynamic feature service so that it will also load backend plugins that have an alpha export but do not export the plugin object in that alpha export. The patch is similar to the fix applied in this PR: backstage/backstage#34535 Assisted-By: Cursor Desktop

…loading Follow-up cleanup after backstage#34535. Use a discriminated union for load results, try alpha before falling back to main, and remove the loop with unreachable branches. Assisted-By: Cursor Desktop Signed-off-by: Stan Lewis <gashcrumb@gmail.com>

gashcrumb · 2026-06-16T13:56:37Z

Have created this PR to address the feedback, think it definitely reads a lot better. Thanks!

…loading Follow-up cleanup after backstage#34535. Use a discriminated union for load results, try alpha before falling back to main, and remove the loop with unreachable branches. Assisted-By: Cursor Desktop Signed-off-by: Stan Lewis <gashcrumb@gmail.com>

Copilot AI review requested due to automatic review settings June 10, 2026 13:33

gashcrumb requested a review from a team as a code owner June 10, 2026 13:33

backstage-goalie Bot added size:medium Medium-sized pull requests receive no change in priority for reviews. waiting-for:review The PR needs a review and will be visible in the review queue unless already assigned an owner. labels Jun 10, 2026

Copilot AI reviewed Jun 10, 2026

View reviewed changes

gashcrumb force-pushed the backend-entrypoint-evaluation branch from c1775a6 to 7005478 Compare June 10, 2026 14:10

schultzp2020 requested a review from Copilot June 10, 2026 14:19

Copilot started reviewing on behalf of schultzp2020 June 10, 2026 14:19 View session

Copilot AI reviewed Jun 10, 2026

View reviewed changes

schultzp2020 approved these changes Jun 10, 2026

View reviewed changes

backstage-goalie Bot added the reviewer-approved The pull request has been approved by a member of the reviewers group and has much higher priority. label Jun 10, 2026

freben self-assigned this Jun 10, 2026

freben approved these changes Jun 16, 2026

View reviewed changes

backstage-goalie Bot added waiting-for:merge The PR has been approved and is awaiting merge. and removed waiting-for:review The PR needs a review and will be visible in the review queue unless already assigned an owner. labels Jun 16, 2026

freben merged commit 69e949d into backstage:master Jun 16, 2026
27 checks passed

gashcrumb mentioned this pull request Jun 16, 2026

refactor(backend-dynamic-feature-service): simplify alpha entrypoint loading #34609

Open

5 tasks

Uh oh!

Conversation

gashcrumb commented Jun 10, 2026

Hey, I just made a Pull Request!

✔️ Checklist

Uh oh!

backstage-goalie Bot commented Jun 10, 2026

Changed Packages

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

schultzp2020 left a comment

Choose a reason for hiding this comment

Uh oh!

freben left a comment

Choose a reason for hiding this comment

Uh oh!

freben Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

freben Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

freben Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

freben Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

freben Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 16, 2026

Uh oh!

gashcrumb commented Jun 16, 2026

Uh oh!

gashcrumb commented Jun 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants