refactor(homepage): narrow main entry point public API by christoph-jerolimov · Pull Request #4852 · redhat-developer/rhdh-plugins

christoph-jerolimov · 2026-09-17T13:04:40Z

Description

Narrow the homepage plugin's main package entry point by moving the plugin implementation into plugin.ts and limiting exports to the default plugin, translations module, and translation resources.

Deprecated public API aliases (homePagePlugin, homePageModule) and other named exports (homepagePlugin, homepageHomeModule, homepageRouteRef) are removed from the main entry point. The demo app and dev shell are updated to use the default plugin import.

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)

Made with Cursor

rhdh-gh-app · 2026-09-17T13:05:05Z

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	`v2.0.0`

rhdh-qodo-merge · 2026-09-17T13:05:33Z

PR Summary by Qodo

Narrow the homepage plugin's public package API

✨ Enhancement 🕐 20-40 Minutes

AI Description

• Restricts the main entry point to the default plugin and translation exports.
• Moves plugin construction behind an internal module and removes deprecated aliases.
• Updates consumers, tests, API reports, and release metadata for the narrower contract.

Diagram

graph TD
  Apps["Demo Apps"] --> Entry["Main Entry"] --> Default["Default Plugin"] --> Internals["Plugin Internals"] --> Extensions["Homepage Extensions"]
  Entry --> Translations["Translation API"]
  Apps --> Subpath["Translation Subpath"] --> Translations

High-Level Assessment

The following are alternative approaches to this PR:

1. Dedicated home-module subpath

➕ Keeps the main entry point narrow
➕ Preserves optional community Home integration for external consumers
➖ Adds another supported package export
➖ Requires separate API reporting and compatibility maintenance

2. Temporary compatibility subpath

➕ Provides consumers a migration path for deprecated aliases
➕ Avoids restoring deprecated names to the main entry point
➖ Extends the deprecation lifecycle
➖ Adds short-lived packaging and documentation overhead

Recommendation: Keep the narrowed root API because it creates a clearer default installation contract. If homepageHomeModule remains a supported integration, expose it through an explicit subpath; otherwise remove its now-internal implementation and tests rather than retaining unreachable package functionality.

Files changed (7) +134 / -143

Refactor (4) +127 / -128

App.tsxAdopt the homepage default export in the demo app +3/-7

Adopt the homepage default export in the demo app
• Replaces named homepage imports with the default plugin import. Stops registering the home compatibility and translation modules in this app configuration.
workspaces/homepage/packages/app/src/App.tsx

index.tsxUpdate development-shell homepage imports +7/-6

Update development-shell homepage imports
• Imports the homepage plugin as the package default and loads translations through the dedicated subpath. The optional community Home module registration is disabled.
workspaces/homepage/plugins/homepage/dev/index.tsx

index.tsReduce the main package entry point +2/-115

Reduce the main package entry point
• Replaces inline plugin construction with focused re-exports. The root now exposes the default homepage plugin, translation module, translation reference, and translation resources.
workspaces/homepage/plugins/homepage/src/index.ts

plugin.tsMove homepage plugin construction into an internal module +115/-0

Move homepage plugin construction into an internal module

• Introduces the implementation module containing the frontend plugin, optional community Home module, translation module, route, and assembled extensions. This preserves implementation-level access while removing those symbols from the package root.

workspaces/homepage/plugins/homepage/src/plugin.ts

Tests (1) +2 / -5

plugin.test.tsTest plugin internals without public aliases +2/-5

Test plugin internals without public aliases
• Imports plugin features directly from the internal implementation module and removes assertions for deprecated alias identity. Existing plugin, home-module, extension, and translation behavior remains covered.
workspaces/homepage/plugins/homepage/src/plugin.test.ts

Other (2) +5 / -10

narrow-homepage-public-api.mdRecord the homepage public API narrowing +5/-0

Record the homepage public API narrowing
• Adds a minor release changeset describing the narrowed main entry point, relocated implementation, and removed deprecated aliases.
workspaces/homepage/.changeset/narrow-homepage-public-api.md

report.api.mdRemove retired homepage exports from the API report +0/-10

Remove retired homepage exports from the API report
• Updates the generated public API contract to omit the home module, named plugin exports, deprecated aliases, and route reference from the package root.
workspaces/homepage/plugins/homepage/report.api.md

rhdh-qodo-merge · 2026-09-17T13:07:11Z

Code Review by Qodo

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

1. Breaking removals ship as a minor update 🐞 Bug ≡ Correctness

Description

The changeset marks this release as minor even though the root entry point removes the public named
plugin, home module, route reference, and deprecated aliases from a stable 2.0 package. Consumers
using any of those exports receive compilation failures without the major-version boundary expected
for an incompatible public API change.

Code

workspaces/homepage/.changeset/narrow-homepage-public-api.md[2]
+'@red-hat-developer-hub/backstage-plugin-homepage': minor

Relevance

●●● Strong
Removing stable public exports is breaking; the changeset should use a major version boundary.
ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The package is currently version 2.0.0, while its new root entry exports only the default plugin,
translation module, and resources; the generated API report confirms the previously public names are
gone.
workspaces/homepage/.changeset/narrow-homepage-public-api.md[1-5]
workspaces/homepage/plugins/homepage/package.json[1-4]
workspaces/homepage/plugins/homepage/src/index.ts[31-35]
workspaces/homepage/plugins/homepage/report.api.md[26-31]
workspaces/homepage/plugins/homepage/report.api.md[299-304]

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 changeset classifies removals from a stable public API as a minor release even though existing imports stop compiling.

## Fix Focus Areas
- workspaces/homepage/.changeset/narrow-homepage-public-api.md[1-3]

## Recommended Fix
Change the homepage package's changeset bump from `minor` to `major`, unless backward-compatible forwarding exports are restored for the removed public names.

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

2. The homepage dev shell fails to build 🐞 Bug ≡ Correctness

Description

dev/index.tsx imports the default plugin through a trailing-slash package specifier that is not
declared by the package exports map. Because the package exports . but not ./, exports-aware
resolution rejects this import when the dev shell is built or started.

Code

workspaces/homepage/plugins/homepage/dev/index.tsx[49]
+import homepagePlugin from '@red-hat-developer-hub/backstage-plugin-homepage/';

Relevance

●●● Strong
The trailing-slash import conflicts with the package exports map and can deterministically break
dev-shell resolution.
ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The changed import uses a trailing slash, while the package exports only the exact root entry and
the translations subpath.
workspaces/homepage/plugins/homepage/dev/index.tsx[49-53]
workspaces/homepage/plugins/homepage/package.json[24-29]
workspaces/homepage/plugins/homepage/src/index.ts[31-35]

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 homepage dev shell imports the package root with a trailing slash, but that subpath is not present in the package exports map.

## Fix Focus Areas
- workspaces/homepage/plugins/homepage/dev/index.tsx[49-49]

## Recommended Fix
Change the default import source to `@red-hat-developer-hub/backstage-plugin-homepage` without the trailing slash.

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

3. ~~Localized homepage text disappears~~ ⊘ Outdated 🐞 Bug ≡ Correctness

Description

App.tsx comments out homepageTranslationsModule while continuing to install the homepage plugin.
When this example application runs in a supported non-English locale, no translation blueprint
registers the bundled homepage messages used by its components and card titles.

Code

workspaces/homepage/packages/app/src/App.tsx[30]
+    // homepageTranslationsModule,

Relevance

●●● Strong
Commenting out the translation module removes localized resources while homepage components still
depend on them.
ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The app keeps the homepage feature but comments out the only module that registers its bundled
German, Spanish, French, Italian, and Japanese resources; homepage rendering consumes that
translation reference.
workspaces/homepage/packages/app/src/App.tsx[20-30]
workspaces/homepage/plugins/homepage/src/plugin.ts[103-113]
workspaces/homepage/plugins/homepage/src/translations/index.ts[21-32]
workspaces/homepage/plugins/homepage/src/hooks/useTranslation.ts[18-26]
workspaces/homepage/plugins/homepage/src/utils/translatedCardRenderer.tsx[39-41]

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 example application still installs the homepage plugin but no longer registers its translation resource.

## Fix Focus Areas
- workspaces/homepage/packages/app/src/App.tsx[20-30]

## Recommended Fix
Import `homepageTranslationsModule` from the package's supported root entry point and restore it as an active feature alongside the default homepage plugin.

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

4. The demo home page loses its widgets 🐞 Bug ≡ Correctness

Description

dev/index.tsx removes homepageHomeModule from the feature list even though the community home
plugin remains installed. With that module absent, the community home page no longer receives the
Red Hat widget variants or the extensions that disable and override its toolkit, joke, and starred
widgets.

Code

workspaces/homepage/plugins/homepage/dev/index.tsx[161]
+    // homepageHomeModule,

Relevance

●●● Strong
Removing the home module while retaining the community home plugin drops the documented widget
integrations and overrides.
ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The dev shell still installs homePlugin, while the removed module is specifically responsible for
attaching the Red Hat widgets and upstream overrides to page:home.
workspaces/homepage/plugins/homepage/dev/index.tsx[47-53]
workspaces/homepage/plugins/homepage/dev/index.tsx[158-163]
workspaces/homepage/plugins/homepage/src/plugin.ts[80-96]
workspaces/homepage/plugins/homepage/src/extensions/homePageCards.tsx[189-231]

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 dev shell still installs the community home plugin but no longer installs the module that integrates the homepage widgets and overrides with it.

## Fix Focus Areas
- workspaces/homepage/plugins/homepage/dev/index.tsx[49-53]
- workspaces/homepage/plugins/homepage/dev/index.tsx[158-163]

## Recommended Fix
Import `homepageHomeModule` directly from the package-internal plugin module for this same-package dev shell and restore it as an active feature, or remove the community home plugin if that integration is intentionally no longer demonstrated.

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

5. The homepage setup guide no longer builds 🐞 Bug ⚙ Maintainability

Description

README.md still tells consumers to import homepagePlugin and homepageHomeModule as named root
exports and describes both as public package features. src/index.ts no longer exports either name,
so copying the documented setup produces unresolved-export errors and the advertised community-home
integration has no public import path.

Code

workspaces/homepage/plugins/homepage/src/index.ts[R31-33]

+export { homepagePlugin as default } from './plugin';

-export { homepageRouteRef } from './homepageRouteRef';
-
-/**
- * Extensions owned by the homepage plugin.
- *
- * Widgets/layout attach to `page:homepage`. Persona filtering via
- * homepage-backend is applied only by that layout.
- */
-const homepageExtensions = [
-  homepagePage,
-  homePageLayoutExtension,
-  onboardingSectionWidget,
-  entitySectionWidget,
-  templateSectionWidget,
-  defaultWidgetsApi,
-  quickAccessApi,
-  quickAccessCardWidget,
-  featuredDocsCardWidget,
-  searchBarWidget,
-  TopVisitedWidget,
-  RecentlyVisitedWidget,
-  catalogStarredWidget,
-];
-
-/**
- * Homepage frontend plugin (`pluginId: homepage`).
- *
- * @public
- */
-export const homepagePlugin = createFrontendPlugin({
-  pluginId: 'homepage',
-  extensions: homepageExtensions,
-  routes: {
-    root: homepageRouteRef,
-  },
-});
-
-/**
- * Optional module for when community `@backstage/plugin-home` is also installed.
- *
- * Mirrors RH widgets onto `page:home` (no RH layout / no homepage-backend
- * filtering) and disables community toolkit / joke demos and overrides the starred widget.
- *
- * @public
- */
-export const homepageHomeModule = createFrontendModule({
-  pluginId: 'home',
-  extensions: [
-    ...communityHomeWidgets,
-    overrideHomeCatalogStarredWidget,
-    disableToolkit,
-    disableRandomJoke,
-  ],
-});
-
-/**
- * @public
- * @deprecated Use {@link homepageHomeModule}.
- */
-export { homepageHomeModule as homePageModule };
-
-/**
- * @public
- * @deprecated Use {@link homepagePlugin}.
- */
-export { homepagePlugin as homePagePlugin };
-
-/**
- * Translation module for the Dynamic Home Page plugin.
- *
- * @public
- */
-export const homepageTranslationsModule = createFrontendModule({
-  pluginId: 'app',
-  extensions: [
-    TranslationBlueprint.make({
-      name: 'homepage-translations',
-      params: {
-        resource: homepageTranslations,
-      },
-    }),
-  ],
-});
+export { homepageTranslationsModule } from './plugin';

Relevance

●●● Strong
README setup instructions reference named exports removed from the package root, causing consumer
compilation failures.
ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The primary README imports and advertises two named exports that the narrowed package root no longer
exposes, including an optional integration that now has no exported subpath.
workspaces/homepage/plugins/homepage/README.md[9-28]
workspaces/homepage/plugins/homepage/README.md[65-86]
workspaces/homepage/plugins/homepage/src/index.ts[31-35]
workspaces/homepage/plugins/homepage/package.json[24-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 package README documents named root exports that this PR removes, leaving installation examples and the export table inaccurate.

## Fix Focus Areas
- workspaces/homepage/plugins/homepage/README.md[9-28]
- workspaces/homepage/plugins/homepage/README.md[65-86]
- workspaces/homepage/plugins/homepage/src/index.ts[31-35]

## Recommended Fix
Rewrite the setup example and export table to use the default plugin import and only supported translation exports, and remove or replace all guidance for the home module unless a supported public subpath is provided.

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

Context sources

✅ Compliance rules (platform): 11 rules

✅ Cross-repo context — repo relationships

Explored: repo: redhat-developer/rhdh (sha: b8140abe)

Review mode: ⚖️ Balanced: This changes a package's public API and runtime entry-point exports, so compatibility and integration risks warrant a complete single-pass review.

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

rhdh-qodo-merge · 2026-09-17T13:07:20Z

Important

The /generate_labels command by Qodo is sunsetting on the 1st of October 2026 and will no longer be available. We recommend switching to the latest Qodo review capabilities. Learn more

codecov · 2026-09-17T13:08:36Z

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4852   +/-   ##
=======================================
  Coverage   60.38%   60.38%           
=======================================
  Files        2672     2672           
  Lines      106387   106387           
  Branches    29922    29927    +5     
=======================================
  Hits        64244    64244           
  Misses      40382    40382           
  Partials     1761     1761

Flag	Coverage Δ	*Carryforward flag
adoption-insights	`84.77% <ø> (ø)`	Carriedforward from b949e30
ai-integrations	`79.83% <ø> (ø)`	Carriedforward from b949e30
app-defaults	`54.82% <ø> (ø)`	Carriedforward from b949e30
augment	`46.67% <ø> (ø)`	Carriedforward from b949e30
boost	`84.97% <ø> (ø)`	Carriedforward from b949e30
bulk-import	`73.12% <ø> (ø)`	Carriedforward from b949e30
cost-management	`13.53% <ø> (ø)`	Carriedforward from b949e30
dcm	`73.47% <ø> (ø)`	Carriedforward from b949e30
e2e-adoption-insights	`60.00% <ø> (ø)`	Carriedforward from b949e30
e2e-extensions	`62.31% <ø> (ø)`	Carriedforward from b949e30
e2e-global-header	`51.82% <ø> (ø)`	Carriedforward from b949e30
e2e-homepage	`61.11% <ø> (ø)`	Carriedforward from b949e30
e2e-intelligent-assistant	`46.01% <ø> (ø)`	Carriedforward from b949e30
e2e-orchestrator	`49.49% <ø> (ø)`	Carriedforward from b949e30
e2e-orchestrator-plugin	`49.48% <ø> (ø)`	Carriedforward from b949e30
e2e-quickstart	`55.21% <ø> (ø)`	Carriedforward from b949e30
e2e-scorecard	`50.00% <ø> (ø)`	Carriedforward from b949e30
e2e-theme	`16.36% <ø> (ø)`	Carriedforward from b949e30
extensions	`58.30% <ø> (ø)`	Carriedforward from b949e30
global-floating-action-button	`71.18% <ø> (ø)`	Carriedforward from b949e30
global-header	`67.76% <ø> (ø)`	Carriedforward from b949e30
homepage	`55.05% <ø> (ø)`
install-dynamic-plugins	`71.77% <ø> (ø)`	Carriedforward from b949e30
intelligent-assistant	`77.99% <ø> (ø)`	Carriedforward from b949e30
konflux	`91.98% <ø> (ø)`	Carriedforward from b949e30
lightspeed	`69.02% <ø> (ø)`	Carriedforward from b949e30
mcp-integrations	`84.46% <ø> (ø)`	Carriedforward from b949e30
orchestrator	`77.69% <ø> (ø)`	Carriedforward from b949e30
quickstart	`63.74% <ø> (ø)`	Carriedforward from b949e30
sandbox	`79.56% <ø> (ø)`	Carriedforward from b949e30
scorecard	`88.71% <ø> (ø)`	Carriedforward from b949e30
theme	`87.91% <ø> (ø)`	Carriedforward from b949e30
translations	`5.12% <ø> (ø)`	Carriedforward from b949e30
x2a	`13.86% <ø> (ø)`	Carriedforward from b949e30

*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 b949e30...c2ad7a1. 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.

Move plugin implementation to plugin.ts and limit the package entry point to the default plugin export and translations module. Remove deprecated aliases and other named exports from the main entry point. Serve the demo homepage at /homepage and redirect / there. Signed-off-by: Christoph Jerolimov <jerolimov+git@redhat.com> Co-authored-by: Cursor <cursoragent@cursor.com>

sonarqubecloud · 2026-09-18T09:20:01Z

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

christoph-jerolimov requested review from a team and Eswaraiahsapram as code owners September 17, 2026 13:04

christoph-jerolimov requested a review from rohitratannagar September 17, 2026 13:04

github-actions Bot added the workspace/homepage label Sep 17, 2026

rhdh-qodo-merge Bot added enhancement New feature or request Tests labels Sep 17, 2026

christoph-jerolimov marked this pull request as draft September 17, 2026 14:08

openshift-ci Bot added the do-not-merge/work-in-progress label Sep 17, 2026

christoph-jerolimov force-pushed the refactor/homepage-narrow-public-api branch from c2ad7a1 to 56bb244 Compare September 18, 2026 09:18

Navigation Menu

refactor(homepage): narrow main entry point public API - #4852

refactor(homepage): narrow main entry point public API#4852
christoph-jerolimov wants to merge 1 commit into
redhat-developer:mainfrom
christoph-jerolimov:refactor/homepage-narrow-public-api

christoph-jerolimov commented Sep 17, 2026

Uh oh!

rhdh-gh-app Bot commented Sep 17, 2026

Uh oh!

rhdh-qodo-merge Bot commented Sep 17, 2026

Uh oh!

rhdh-qodo-merge Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

rhdh-qodo-merge Bot commented Sep 17, 2026

Uh oh!

codecov Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

sonarqubecloud Bot commented Sep 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

christoph-jerolimov commented Sep 17, 2026

Description

Checklist

Uh oh!

rhdh-gh-app Bot commented Sep 17, 2026

Changed Packages

Uh oh!

rhdh-qodo-merge Bot commented Sep 17, 2026

PR Summary by Qodo

Uh oh!

rhdh-qodo-merge Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

rhdh-qodo-merge Bot commented Sep 17, 2026

Uh oh!

codecov Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

sonarqubecloud Bot commented Sep 18, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

rhdh-qodo-merge Bot commented Sep 17, 2026 •

edited

Loading

codecov Bot commented Sep 17, 2026 •

edited

Loading