chore(theme): promote theme NFS plugin from /alpha to stable

[ciiay]

Hey, I just made a Pull Request!

for https://redhat.atlassian.net/browse/RHIDP-14522

✔️ 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-legacy	workspaces/theme/packages/app-legacy	none	v0.0.0
app	workspaces/theme/packages/app	none	v0.0.0
@red-hat-developer-hub/backstage-plugin-theme	workspaces/theme/plugins/theme	major	v0.15.0

[rhdh-qodo-merge]

PR Summary by Qodo

Promote theme NFS module export to stable entry point (keep legacy under /legacy)

✨ Enhancement 📝 Documentation ⚙️ Configuration changes 🧪 Tests 🕐 20-40 Minutes

AI Description

• Promote rhdhThemeModule from @…/theme/alpha to the package root export.
• Move OFS (legacy) theme helpers to @…/theme/legacy and add explicit export paths.
• Update app/dev imports and docs; add a smoke test and regenerated API reports.

Diagram

graph TD
  App["Theme app (NFS)"] -->|imports| Pkg["@rhdh/backstage-plugin-theme"] -->|exports| Mod["rhdhThemeModule"]
  Pkg --> Alpha["./alpha (deprecated)"]
  Pkg --> Legacy["./legacy (OFS helpers)"]
  Pkg --> RExport["./rhdh-theme-module (default)"]
  Docs["README.md"] -->|documents| Pkg
  Test["nfsExports.test.tsx"] -->|verifies| Mod

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep `./alpha` re-exporting `rhdhThemeModule` (deprecated shim)

• ➕ Avoids a hard break for any downstream consumers still importing from /alpha
• ➕ Allows a deprecation window that matches a minor version bump
• ➖ Prolongs support surface and delays removal of /alpha
• ➖ Requires follow-up removal plan and versioning discipline

2. Ship a codemod/migration note (explicit breaking-change callout)

• ➕ Makes upgrading safer for consumers by providing a clear mechanical change
• ➕ Reduces reviewer/maintainer time spent on upgrade support
• ➖ Extra maintenance for tooling/docs
• ➖ May be overkill if no external consumers exist

Recommendation: Current approach (promote NFS to root, move OFS helpers under /legacy) is the right long-term API shape. However, consider whether leaving ./alpha as an empty export is an unintended breaking change; if any downstream code imports rhdhThemeModule from /alpha, this will fail at compile-time. If you need to keep this as a minor bump, a deprecated shim re-export from ./alpha for at least one release would better match semver expectations.

Files changed (15) +365 / -55

Enhancement (3) +52 / -17

App.tsxSwitch app import to stable 'rhdhThemeModule' export +1/-1

Switch app import to stable 'rhdhThemeModule' export

• Updates the app to import 'rhdhThemeModule' from the package root instead of the '/alpha' entry. Ensures the app registers the now-stable NFS theme module.

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

index.tsPromote NFS module to root entry point and re-export legacy surface +34/-16

Promote NFS module to root entry point and re-export legacy surface

• Defines and exports 'rhdhThemeModule' from the package root using 'createFrontendModule' and 'ThemeBlueprint' generated from 'getAllThemes()'. Re-exports legacy functionality via 'legacyExports' to preserve compatibility while formalizing the new API shape.

workspaces/theme/plugins/theme/src/index.ts

rhdhThemeModuleExport.tsAdd dedicated default export for 'rhdhThemeModule' entry +17/-0

Add dedicated default export for 'rhdhThemeModule' entry

• Introduces a small re-export file that default-exports 'rhdhThemeModule'. Supports the explicit './rhdh-theme-module' package export path.

workspaces/theme/plugins/theme/src/rhdhThemeModuleExport.ts

Bug fix (1) +1 / -0

Sidebar.tsxSkip notifications page entry in sidebar nav +1/-0

Skip notifications page entry in sidebar nav

• Adds 'page:notifications' to the list of skipped nav items. Prevents duplicate/undesired sidebar rendering when a dedicated 'NotificationsSidebarItem' is used.

workspaces/theme/packages/app/src/modules/nav/Sidebar.tsx

Refactor (2) +38 / -32

index.tsDeprecate alpha entry point and remove its exports +4/-32

Deprecate alpha entry point and remove its exports

• Replaces the previous alpha implementation with a deprecation notice and an empty export. Signals consumers to import from the root package entry instead.

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

legacyExports.tsCreate dedicated legacy export barrel (OFS helpers) +34/-0

Create dedicated legacy export barrel (OFS helpers)

• Moves the previous root exports (icons, fonts, hooks, themes, components, and types) into a dedicated legacy barrel. This file underpins both the './legacy' entry point and compatibility re-exports.

workspaces/theme/plugins/theme/src/legacyExports.ts

Tests (1) +23 / -0

nfsExports.test.tsxAdd smoke test asserting 'rhdhThemeModule' export exists +23/-0

Add smoke test asserting 'rhdhThemeModule' export exists

• Adds a minimal unit test that imports from the root index and asserts 'rhdhThemeModule' is defined. Helps catch accidental export regressions.

workspaces/theme/plugins/theme/src/nfsExports.test.tsx

Documentation (5) +237 / -5

README.mdDocument stable NFS entry point and '/legacy' exports +15/-0

Document stable NFS entry point and '/legacy' exports

• Adds guidance that NFS is now the primary entry point and legacy helpers live under './legacy'. Provides an example showing how to register 'rhdhThemeModule' in an NFS app.

workspaces/theme/plugins/theme/README.md

report-alpha.api.mdRemove alpha API surface report content for theme module export +0/-5

Remove alpha API surface report content for theme module export

• Updates the alpha API report to reflect that 'rhdhThemeModule' is no longer exported from the '/alpha' entry. Keeps API Extractor outputs consistent with the new export layout.

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

report-legacy.api.mdAdd API Extractor report for '/legacy' exports +205/-0

Add API Extractor report for '/legacy' exports

• Introduces an API report capturing the legacy (OFS) surface: hooks, theme accessors, components, and type exports. Reflects the new dedicated './legacy' entry point.

workspaces/theme/plugins/theme/report-legacy.api.md

report-rhdh-theme-module.api.mdAdd API Extractor report for default module export entry +13/-0

Add API Extractor report for default module export entry

• Adds an API report for the './rhdh-theme-module' entry, which default-exports a 'FrontendModule'. Makes the default-exported module surface explicit and tracked.

workspaces/theme/plugins/theme/report-rhdh-theme-module.api.md

report.api.mdExpose 'rhdhThemeModule' in root API report +4/-0

Expose 'rhdhThemeModule' in root API report

• Updates the root API report to include the 'FrontendModule' type import and the public 'rhdhThemeModule' export. Aligns published API with the new stable NFS entry point.

workspaces/theme/plugins/theme/report.api.md

Other (3) +14 / -1

graduate-nfs-alpha-to-stable.mdAdd changeset for promoting NFS theme module to stable entry point +5/-0

Add changeset for promoting NFS theme module to stable entry point

• Introduces a minor-version changeset documenting the graduation of the NFS theme module from './alpha' to the primary package entry. Notes that legacy OFS exports are available via './legacy'.

workspaces/theme/.changeset/graduate-nfs-alpha-to-stable.md

index.tsxUpdate dev app to import theme module from root source index +1/-1

Update dev app to import theme module from root source index

• Switches the dev setup import from 'src/alpha' to 'src' to match the new stable entry point. Keeps local development aligned with published exports.

workspaces/theme/plugins/theme/dev/index.tsx

package.jsonAdd '/legacy' and '/rhdh-theme-module' export paths +8/-0

Add '/legacy' and '/rhdh-theme-module' export paths

• Extends 'exports' and 'typesVersions' to include './legacy' and './rhdh-theme-module'. Keeps './alpha' mapped while introducing stable, explicit entry points for legacy helpers and the module default export.

workspaces/theme/plugins/theme/package.json

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.36%. Comparing base (77b7f15) to head (f18a132).
⚠️ Report is 56 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3954      +/-   ##
==========================================
+ Coverage   57.34%   57.36%   +0.02%     
==========================================
  Files        2382     2382              
  Lines       95599    95612      +13     
  Branches    26747    26747              
==========================================
+ Hits        54824    54851      +27     
+ Misses      39273    39259      -14     
  Partials     1502     1502              

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

*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 77b7f15...f18a132. 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: c7eaff8f)

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

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

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

1. Alpha export removed 🐞 Bug ≡ Correctness

Description

@red-hat-developer-hub/backstage-plugin-theme/alpha no longer exports rhdhThemeModule (it now
has export {}) even though package.json still exposes the ./alpha subpath, so any existing
.../alpha named import will fail to compile. This is effectively a breaking change while the
changeset declares a minor bump and multiple apps in this repo still import from /alpha.

Code

workspaces/theme/plugins/theme/src/alpha/index.ts[R18-25]

+ * The NFS theme module has graduated to the primary package entry point.
+ * Import `rhdhThemeModule` from `@red-hat-developer-hub/backstage-plugin-theme` instead.
 *
+ * @deprecated Use the root import instead.
 * @packageDocumentation
 */

-import { createFrontendModule } from '@backstage/frontend-plugin-api';
-import { ThemeBlueprint } from '@backstage/plugin-app-react';
-
-import '../assets/fonts/font.min.css';
-
-import { getAllThemes } from '../themes';
-
-const rhdhThemeExtensions = getAllThemes().map(appTheme =>
-  ThemeBlueprint.make({
-    name: appTheme.id,
-    params: {
-      theme: {
-        id: appTheme.id,
-        title: appTheme.title,
-        variant: appTheme.variant,
-        icon: appTheme.icon,
-        Provider: appTheme.Provider,
-      },
-    },
-  }),
-);
-
-/*
- * @alpha
- */
-export const rhdhThemeModule = createFrontendModule({
-  pluginId: 'app',
-  extensions: rhdhThemeExtensions,
-});
+export {};

Relevance

⭐⭐⭐ High

Repo reviewers usually act on breaking public API/export changes and align changesets/migration
notes accordingly.

PR-#2609
PR-#3417

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The ./alpha entrypoint is still published via exports, but its implementation file exports
nothing; meanwhile, other apps in this monorepo still import rhdhThemeModule from the /alpha
path, which will now be a missing export at type-check/build time. The changeset marks this as a
minor bump, increasing the likelihood this was unintended.

workspaces/theme/plugins/theme/src/alpha/index.ts[17-25]
workspaces/theme/plugins/theme/package.json[23-32]
workspaces/boost/packages/app/src/App.tsx[17-26]
workspaces/bulk-import/packages/app/src/App.tsx[17-30]
workspaces/theme/.changeset/graduate-nfs-alpha-to-stable.md[1-5]

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 still exports the `./alpha` entrypoint, but `src/alpha/index.ts` exports nothing (`export {}`), breaking consumers that import `rhdhThemeModule` from `@red-hat-developer-hub/backstage-plugin-theme/alpha`.

## Issue Context
This repo still contains multiple workspaces that import `rhdhThemeModule` from `/alpha`. The changeset also marks this as a `minor` release, so preserving backward compatibility for `/alpha` is important unless you intend to do a breaking release and update all call sites.

## Fix Focus Areas
- Re-introduce a deprecated re-export from the alpha entrypoint (e.g., `export { rhdhThemeModule } from '../index';` with `/** @deprecated ... */`).
- Ensure API reports stay consistent (alpha report should again include `rhdhThemeModule` if you re-export it).
- If removal is intentional instead: update all repo call sites to import from the root entrypoint and change the changeset to a breaking/major bump.

### Targeted code locations
- workspaces/theme/plugins/theme/src/alpha/index.ts[17-25]
- workspaces/theme/plugins/theme/package.json[23-33]
- workspaces/theme/.changeset/graduate-nfs-alpha-to-stable.md[1-5]

ⓘ 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.}

[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

[rohitratannagar]

Tested in rhdh-local
/lgtm