fix(homepage): export homePagePlugin as alpha default for NFS dynamic installs

[debsmita1]

Hey, I just made a Pull Request!

Resolves:
https://redhat.atlassian.net/browse/RHDHBUGS-3512

Solution description:

• Exported homePagePlugin as the alpha default: upstream @backstage/plugin-home with homepage layout/widgets applied via withOverrides.
• Module Federation / dynamic NFS installs now register page:home without requiring a separate @backstage/plugin-home install on the host.
• Keep homePageModule for apps that already register homePlugin (or discover it via app.packages); avoid double-loading home.
• Update workspace app, README, API report, and tests accordingly; drop the redundant @backstage/plugin-home dependency from the NFS app package.

✔️ 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)

[rhdh-gh-app]

Important

This PR includes changes that affect public-facing API. Please ensure you are adding/updating documentation for new features or behavior.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
app	workspaces/homepage/packages/app	none	v0.0.0
@red-hat-developer-hub/backstage-plugin-homepage	workspaces/homepage/plugins/homepage	minor	v1.17.0

[rhdh-qodo-merge]

PR Summary by Qodo

fix(homepage): export homePagePlugin as alpha default for NFS dynamic installs

🐞 Bug fix 📝 Documentation 🧪 Tests 🕐 20-40 Minutes

AI Description

• Exports homePagePlugin (upstream @backstage/plugin-home + homepage layout/widgets via
 withOverrides) as the alpha default.
• Fixes Module Federation / dynamic NFS installs so page:home registers without requiring a
 separate @backstage/plugin-home host install.
• Keeps homePageModule for hosts that already register homePlugin, avoiding double-loading
 home.
• Removes the now-redundant @backstage/plugin-home dependency from the workspace app package and
 updates README, API report, dev app, and tests accordingly.

Diagram

graph TD
  subgraph HomepagePlugin["homepage plugin alpha"]
    HP["@backstage/plugin-home"] --> WO["withOverrides layout/widgets"] --> PP["homePagePlugin default export"]
    HP --> MOD["homePageModule"]
  end
  PP -->|"registers"| PAGE["page:home extension"]
  MOD -->|"extends existing"| HOST["Host homePlugin"]
  NFS["Dynamic NFS Module Federation host"] -->|"loads alpha default"| PP
  APP["Workspace App.tsx"] -->|"imports"| PP

  subgraph Legend
    direction LR
    _svc([Plugin/Module]) ~~~ _ext{{External Host}}
  end

Loading

High-Level Assessment

Using OverridableFrontendPlugin.withOverrides on the upstream homePlugin is the correct approach: it lets Module Federation's dynamicFrontendFeaturesLoader register a single self-contained FrontendPlugin (satisfying page:home) instead of a FrontendModule that depends on the host already loading @backstage/plugin-home. Keeping homePageModule as a secondary export preserves backward compatibility for hosts that already register homePlugin themselves, avoiding a breaking change while fixing the NFS dynamic-install bug.

Files changed (10) +264 / -41

Enhancement (1) +47 / -19

index.tsIntroduce homePagePlugin built via withOverrides and set as default export +47/-19

Introduce homePagePlugin built via withOverrides and set as default export

• Extracts shared homePageExtensions array, creates homePagePlugin from upstream homePlugin.withOverrides using those extensions, keeps homePageModule for existing home plugin hosts, and changes the module's default export from homePageModule to homePagePlugin.

workspaces/homepage/plugins/homepage/src/alpha/index.ts

Bug fix (2) +4 / -4

App.tsxSwitch workspace app to use homePagePlugin +2/-2

Switch workspace app to use homePagePlugin

• Replaces homePageModule with homePagePlugin in the app's feature list to register page:home without a separate home plugin install.

workspaces/homepage/packages/app/src/App.tsx

index.tsxUpdate dev app to use homePagePlugin +2/-2

Update dev app to use homePagePlugin

• Replaces homePageModule import and feature registration with homePagePlugin in the dev sandbox app.

workspaces/homepage/plugins/homepage/dev/index.tsx

Tests (1) +13 / -2

alpha.test.tsAdd tests for homePagePlugin default export +13/-2

Add tests for homePagePlugin default export

• Adds assertions verifying homePagePlugin is a FrontendPlugin with id 'home' and is the module's default export, alongside existing homePageModule tests.

workspaces/homepage/plugins/homepage/src/alpha/alpha.test.ts

Documentation (2) +18 / -9

home-plugin-overrides.mdAdd changeset for homePagePlugin alpha default change +5/-0

Add changeset for homePagePlugin alpha default change

• Documents the minor version bump for backstage-plugin-homepage, explaining the new homePagePlugin default export and NFS behavior.

workspaces/homepage/.changeset/home-plugin-overrides.md

README.mdDocument homePagePlugin as recommended alpha export +13/-9

Document homePagePlugin as recommended alpha export

• Updates usage example to homePagePlugin, adds a warning against double-registering @backstage/plugin-home, and reworks the modules/extensions table to distinguish homePagePlugin from homePageModule.

workspaces/homepage/plugins/homepage/README.md

Other (4) +182 / -7

knip-report.mdRegenerate knip report reflecting removed dependency +1/-2

Regenerate knip report reflecting removed dependency

• Removes the @backstage/plugin-home unused dependency entry after it was dropped from package.json.

workspaces/homepage/packages/app/knip-report.md

package.jsonDrop redundant @backstage/plugin-home dependency +0/-1

Drop redundant @backstage/plugin-home dependency

• Removes the direct @backstage/plugin-home dependency from the workspace app since homePagePlugin now bundles it via withOverrides.

workspaces/homepage/packages/app/package.json

report-alpha.api.mdRegenerate API report for new homePagePlugin export +181/-3

Regenerate API report for new homePagePlugin export

• API Extractor report now reflects homePagePlugin as an OverridableFrontendPlugin default export alongside the retained homePageModule.

workspaces/homepage/plugins/homepage/report-alpha.api.md

yarn.lockUpdate lockfile for removed plugin-home dependency +0/-1

Update lockfile for removed plugin-home dependency

• Removes @backstage/plugin-home entry from the app package's resolved dependencies in the lockfile.

workspaces/homepage/yarn.lock

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.80%. Comparing base (e31ec88) to head (f169e75).
⚠️ Report is 5 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4032   +/-   ##
=======================================
  Coverage   57.80%   57.80%           
=======================================
  Files        2393     2393           
  Lines       95919    95919           
  Branches    26810    26817    +7     
=======================================
  Hits        55447    55447           
  Misses      40156    40156           
  Partials      316      316           

Flag	Coverage Δ		*Carryforward flag
adoption-insights	84.54% <ø> (ø)		Carriedforward from e31ec88
ai-integrations	69.06% <ø> (ø)		Carriedforward from e31ec88
app-defaults	69.79% <ø> (ø)		Carriedforward from e31ec88
augment	46.67% <ø> (ø)		Carriedforward from e31ec88
boost	75.92% <ø> (ø)		Carriedforward from e31ec88
bulk-import	72.55% <ø> (ø)		Carriedforward from e31ec88
cost-management	13.55% <ø> (ø)		Carriedforward from e31ec88
dcm	60.72% <ø> (ø)		Carriedforward from e31ec88
extensions	56.48% <ø> (ø)		Carriedforward from e31ec88
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from e31ec88
global-header	62.17% <ø> (ø)		Carriedforward from e31ec88
homepage	47.46% <ø> (ø)
install-dynamic-plugins	56.77% <ø> (ø)		Carriedforward from e31ec88
intelligent-assistant	74.06% <ø> (ø)		Carriedforward from e31ec88
konflux	91.98% <ø> (ø)		Carriedforward from e31ec88
lightspeed	69.02% <ø> (ø)		Carriedforward from e31ec88
mcp-integrations	83.40% <ø> (ø)		Carriedforward from e31ec88
orchestrator	66.79% <ø> (ø)		Carriedforward from e31ec88
quickstart	65.04% <ø> (ø)		Carriedforward from e31ec88
sandbox	79.56% <ø> (ø)		Carriedforward from e31ec88
scorecard	84.94% <ø> (ø)		Carriedforward from e31ec88
theme	83.89% <ø> (ø)		Carriedforward from e31ec88
translations	5.12% <ø> (ø)		Carriedforward from e31ec88
x2a	79.31% <ø> (ø)		Carriedforward from e31ec88

*This pull request uses carry forward flags. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e31ec88...f169e75. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Context used

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

✅ Compliance rules (platform): 11 rules

✅ Cross-repo context

  Explored: repo: redhat-developer/rhdh (sha: 6bcb0141)

  Explored: repo: redhat-developer/rhdh-local (sha: 2ae9e8c8)

  Explored: repo: redhat-developer/rhdh-operator (sha: 24fffa94)

  Not relevant to this PR: redhat-developer/rhdh-chart

1. Dev app loads home twice 🐞 Bug ≡ Correctness

Description

The dev entry explicitly registers homePagePlugin, while app.packages: all can also discover the
directly depended-on upstream homePlugin. Both are distinct frontend plugins with ID home,
causing duplicate-plugin registration when starting the NFS development app.

Code

workspaces/homepage/plugins/homepage/dev/index.tsx[156]

+    homePagePlugin,

Relevance

⭐⭐⭐ High

Deterministic duplicate registration contradicts the PR’s explicit single-home-plugin intent and
documentation.

PR-#3542

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The dev app adds the overridden plugin explicitly, while workspace package discovery is enabled and
the package directly declares upstream @backstage/plugin-home. The project documentation confirms
that discovering upstream home while using homePagePlugin loads the home plugin twice.

workspaces/homepage/plugins/homepage/dev/index.tsx[151-163]
workspaces/homepage/app-config.yaml[1-5]
workspaces/homepage/plugins/homepage/package.json[50-60]
workspaces/homepage/plugins/homepage/README.md[29-29]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The NFS development app explicitly registers `homePagePlugin` while package discovery can register the original `@backstage/plugin-home`. These are distinct frontend plugin objects with the same `home` ID and must not be loaded together.

## Issue Context
The workspace enables `app.packages: all`, and the homepage package directly depends on `@backstage/plugin-home`. The README also explicitly warns that this combination double-loads the home plugin.

## Fix Focus Areas
- workspaces/homepage/plugins/homepage/dev/index.tsx[151-163]
- workspaces/homepage/app-config.yaml[1-5]
- workspaces/homepage/plugins/homepage/package.json[50-60]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}