feat(global-header): Promote global-header NFS plugin from /alpha to …

[rohitratannagar]

Summary

Jira: https://redhat.atlassian.net/browse/RHIDP-14169

after changes

Screen.Recording.2026-07-06.at.12.39.32.AM.mov

Promotes the global-header NFS (New Frontend System) plugin from /alpha to stable exports.

Restructures the Global Header plugin so the New Frontend System (NFS) becomes the default entry point. Old Frontend System (OFS) APIs move to a dedicated ./legacy export (deprecated). Translations remain at /alpha.

Previously, NFS lived under src/alpha and was imported via:

@red-hat-developer-hub/backstage-plugin-global-header/alpha

while OFS was the default package export.

This PR flips that relationship:

• NFS is now the default package entry point.
• Legacy/OFS components move to the new ./legacy subpath (deprecated).
• /alpha retains only translation exports; NFS APIs are no longer available from /alpha.
• All NFS APIs are promoted from @alpha to @public.
• Adds dedicated Module Federation entry points so NFS can discover Global Header extensions through dynamicFrontendFeaturesLoader().

---

fix

• Adds the missing name parameter to the TranslationBlueprint.make() call in the
  stable (non-alpha) global-header plugin export. Without it, the extension ID is
  ambiguous and can collide with other unnamed translation extensions at runtime. And with the name they can be optionally disabled in the app.

      app:
          extensions:
               - translation:app/global-header-translations: false

Test plan

• Verify yarn tsc:full passes in the global-header workspace
• Verify yarn build:api-reports:only --ci passes
• Confirm the global-header translations load correctly in dev mode (yarn start)

Key Changes

Change	Reason
src/alpha/index.ts → src/index.ts	Makes NFS the default package entry point
Legacy exports moved to src/legacy.ts	Separates deprecated OFS APIs behind /legacy
/alpha retains only translations	Translations remain at /alpha per graduation pattern; NFS APIs removed
Added PluginRoot Scalprum exposed module	Enables legacy dynamic plugin resolution
Added module: Legacy to OFS mount points	Allows the dynamic loader to distinguish legacy modules from NFS extensions
Promoted all NFS exports from @alpha to @public	Marks NFS APIs as production-ready
Added globalHeaderModuleExport.ts	Exposes globalHeaderModule as a default export for Module Federation
Added globalHeaderTranslationsModuleExport.ts	Exposes translation module as a default export
Updated app imports	app uses the root package, app-legacy imports from /legacy

---

Migration Guide

NFS (Recommended)

Before

import { globalHeaderModule } from '@red-hat-developer-hub/backstage-plugin-global-header/alpha';
import { globalHeaderTranslationsModule } from '@red-hat-developer-hub/backstage-plugin-global-header/alpha';
import { GlobalHeaderComponentBlueprint } from '@red-hat-developer-hub/backstage-plugin-global-header/alpha';

After

import {
  globalHeaderModule,
  globalHeaderTranslationsModule,
  GlobalHeaderComponentBlueprint,
} from '@red-hat-developer-hub/backstage-plugin-global-header';

---

OFS (Legacy)

Before

import {
  GlobalHeader,
  globalHeaderTranslations,
  GlobalHeaderComponent,
  defaultGlobalHeaderComponentsMountPoints,
} from '@red-hat-developer-hub/backstage-plugin-global-header';

After

import {
  GlobalHeader,
  globalHeaderTranslations,
  GlobalHeaderComponent,
  defaultGlobalHeaderComponentsMountPoints,
} from '@red-hat-developer-hub/backstage-plugin-global-header/legacy';

---

Testing

NFS Mode

1. Export the plugin:

cd workspaces/global-header/plugins/global-header
yarn install
sudo npx @red-hat-developer-hub/cli plugin export --dev --dynamic-plugins-root /path/to/rhdh-local/local-plugins

2. Enable NFS:

APP_CONFIG_app_packageName=app-next
ENABLE_STANDARD_MODULE_FEDERATION=true

3. Enable the local plugin in dynamic-plugins.override.yaml.

4. Configure extensions:

app:
  extensions:
    - app-root-wrapper:app/global-header
    - translation:app/global-header-translations
    - api:app/app-language:
        config:
          availableLanguages: ['en', 'de', 'es', 'fr', 'it', 'ja']
          defaultLanguage: 'en'

5. Start RHDH Local:

podman compose up -d

6. Verify Module Federation:

http://localhost:7007/.backstage/dynamic-features/remotes

Expected:

• GlobalHeaderModuleExport
• GlobalHeaderTranslationsModuleExport

---

OFS Mode

Configure every Global Header mount point using:

module: Legacy

Then start RHDH Local:

podman compose up -d

---

Checklist

• Added a changeset
• Updated documentation
• Added/updated tests
• Added screenshots (UI changes)

[github-actions]

This pull request adds a new top-level directory under workspaces/. Please follow Submitting a Pull Request for a New Workspace in CONTRIBUTING.md.

[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/global-header/packages/app-legacy	none	v0.0.0
app	workspaces/global-header/packages/app	none	v0.0.0
@red-hat-developer-hub/backstage-plugin-global-header	workspaces/global-header/plugins/global-header	minor	v1.22.0

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 54.00%. Comparing base (d86f9c6) to head (be6f3d1).
⚠️ Report is 318 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3413   +/-   ##
=======================================
  Coverage   54.00%   54.00%           
=======================================
  Files        2403     2404    +1     
  Lines       87620    87631   +11     
  Branches    24260    24263    +3     
=======================================
+ Hits        47315    47322    +7     
- Misses      38752    38755    +3     
- Partials     1553     1554    +1     

Flag	Coverage Δ		*Carryforward flag
adoption-insights	83.58% <ø> (ø)		Carriedforward from 7e15cbe
ai-integrations	70.03% <ø> (ø)		Carriedforward from 7e15cbe
app-defaults	69.60% <ø> (ø)		Carriedforward from 7e15cbe
augment	46.39% <ø> (ø)		Carriedforward from 7e15cbe
bulk-import	72.86% <ø> (ø)		Carriedforward from 7e15cbe
cost-management	17.48% <ø> (ø)		Carriedforward from 7e15cbe
dcm	59.63% <ø> (ø)		Carriedforward from 7e15cbe
extensions	62.17% <ø> (ø)		Carriedforward from 7e15cbe
global-floating-action-button	74.30% <ø> (ø)		Carriedforward from 7e15cbe
global-header	61.64% <75.00%> (+0.01%)	⬆️
homepage	51.52% <ø> (ø)		Carriedforward from 7e15cbe
install-dynamic-plugins	56.23% <ø> (ø)		Carriedforward from 7e15cbe
konflux	91.01% <ø> (ø)		Carriedforward from 7e15cbe
lightspeed	68.49% <ø> (ø)		Carriedforward from 7e15cbe
mcp-integrations	85.46% <ø> (ø)		Carriedforward from 7e15cbe
orchestrator	37.33% <ø> (ø)		Carriedforward from 7e15cbe
quickstart	62.09% <ø> (ø)		Carriedforward from 7e15cbe
sandbox	79.56% <ø> (ø)		Carriedforward from 7e15cbe
scorecard	83.93% <ø> (ø)		Carriedforward from 7e15cbe
theme	64.54% <ø> (ø)		Carriedforward from 7e15cbe
translations	8.49% <ø> (ø)		Carriedforward from 7e15cbe
x2a	78.79% <ø> (ø)		Carriedforward from 7e15cbe

*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 d86f9c6...be6f3d1. 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.

[github-actions]

This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution!

[debsmita1]

Tested the changes on RHDH NFS shell (redhat-developer/rhdh#5115)

Screen.Recording.2026-07-20.at.4.09.39.PM.mov

/lgtm

[ciiay]

Thanks for the pr 👏

It looks mostly good. Just looking at the graduation pattern from #3530 : NFS → root, OFS → /legacy, translations remain at /alpha. The code here matches that, but the PR description/changeset still say existing /alpha NFS imports keep working as re-exports — that doesn’t match the code or #3530.

Please align the description/changeset with the #3530 wording (“translations remain at /alpha”), and update in-repo consumers that still import NFS APIs from global-header/alpha (e.g. quickstart, app-defaults) to use the stable root export.

[openshift-ci]

New changes are detected. LGTM label has been removed.

[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]

Thanks for the pr 👏

It looks mostly good. Just looking at the graduation pattern from #3530 : NFS → root, OFS → /legacy, translations remain at /alpha. The code here matches that, but the PR description/changeset still say existing /alpha NFS imports keep working as re-exports — that doesn’t match the code or #3530.

Please align the description/changeset with the #3530 wording (“translations remain at /alpha”), and update in-repo consumers that still import NFS APIs from global-header/alpha (e.g. quickstart, app-defaults) to use the stable root export.

updated!!

[its-mitesh-kumar]

Approving based on #3413

[divyanshiGupta]

@rohitratannagar please move all the files under alpha to src as we are removing the ./alpha subpath and moving the apis to main . entry point as you already know so it doesnt make sense to keep the files under alpha sub-folder. Please refer - #3530. cc: @rohitkrai03

[rohitratannagar]

@divyanshiGupta Thanks for review,
Components are being exported from the index.ts only (that is . entry point), so moving out these components from alpha will create mess, as there is already components folder inside src. If it is regarding the code-readability / conventions, please let me know. I will update it 🙂.

[divyanshiGupta]

It is about making the code ready in a way that it can just be removed easily in the next release. So the NFS related code should go into components and anything OFS can go into /legacy. Global Header is a bit unique in that respect because it creates a lot of dynamic plugin extensions and components that only work in old scalprum based system. And the alpha folder has all new components related to NFS. Some of the components will still be relevant in NFS because it uses them as base but anything only used for OFS should go into legacy.

[divyanshiGupta]

cc: @rohitratannagar ^^