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

[divyanshiGupta]

Hey, I just made a Pull Request!

Story: https://redhat.atlassian.net/browse/RHIDP-14167

Graduate the New Frontend System (NFS) plugin from the ./alpha export to the primary ./ entry point. OFS (legacy) exports are now available at ./legacy. Translations remain at ./alpha.

Option 1: Quickstart Workspace NFS App (rhdh-plugins)

Screen.Recording.2026-06-26.at.12.09.04.PM.mov

This is the simplest way to test the plugin with all dependencies pre-wired.

Steps

cd workspaces/quickstart
yarn start

The NFS app imports the graduated quickstart exports from the main entry point:

import {
  quickstartInitModule,
  quickstartTranslationsModule,
} from '@red-hat-developer-hub/backstage-plugin-quickstart';

Option 2: RHDH app-next (Dynamic Module Federation)

Screen.Recording.2026-06-26.at.1.13.30.PM.mov

This tests the plugin as a dynamically loaded module federation remote in the showcase's NFS shell.

Step 1: Bundle the quickstart plugin for module federation

From the rhdh-plugins repo:

cd workspaces/quickstart/plugins/quickstart
npx backstage-cli package bundle \
  --output-destination /path/to/backstage-showcase/dynamic-plugins-root

This produces a module federation bundle at:

dynamic-plugins-root/red-hat-developer-hub-backstage-plugin-quickstart/

The bundle automatically exposes three entry points:

• . — the NFS createFrontendPlugin default export (drawer + help menu item)
• quickstart-init-module — the init module (first-visit auto-open)
• quickstart-translations-module — the translations module

Step 2: Add infrastructure dependencies to app-next

The quickstart plugin's extensions attach to parent extensions provided by the app drawer and global header. These infrastructure modules must be present in the app for quickstart to render.

Add them to packages/app-next/package.json:

"dependencies": {
  "@red-hat-developer-hub/backstage-plugin-app-react": "0.0.5",
  "@red-hat-developer-hub/backstage-plugin-global-header": "1.21.5",
  "@red-hat-developer-hub/backstage-plugin-theme": "0.14.7"
}

Notes:

• The quickstart plugin itself is not added here — it is loaded dynamically via module federation (Step 1).
• app-react and theme have Backstage role web-library and cannot be bundled as module federation remotes, so they must be static dependencies.
• global-header has role frontend-plugin and could alternatively be bundled dynamically via backstage-cli package bundle, but is added statically here since the rhdh app-next does not yet include it by default.

Then update packages/app-next/src/App.tsx to include the modules:

import { createApp } from '@backstage/frontend-defaults';
import { dynamicFrontendFeaturesLoader } from '@backstage/frontend-dynamic-feature-loader';
// These imports use /alpha because app-react, global-header, and theme
// have not yet been graduated to their main entry points.
import { appDrawerModule } from '@red-hat-developer-hub/backstage-plugin-app-react/alpha';
import {
  globalHeaderModule,
  globalHeaderTranslationsModule,
} from '@red-hat-developer-hub/backstage-plugin-global-header/alpha';
import { rhdhThemeModule } from '@red-hat-developer-hub/backstage-plugin-theme/alpha';
// ...other imports

const app = createApp({
  features: [
    // ...existing plugins
    appDrawerModule,
    globalHeaderModule,
    globalHeaderTranslationsModule,
    rhdhThemeModule,
    dynamicFrontendFeaturesLoader(),
  ],
});

Run yarn install after updating package.json.

Step 3: Configure app-config.local.yaml

Create or update app-config.local.yaml in the rhdh root:

app:
  baseUrl: http://localhost:7007
  extensions:
    - app-root-wrapper:app/global-header: true
    - app-root-wrapper:app/drawer: true
    - api:app/app-language:
        config:
          availableLanguages: ['en', 'de', 'es', 'fr', 'it', 'ja']
          defaultLanguage: 'en'

  quickstart:
    - title: Set up authentication
      titleKey: steps.setupAuthentication.title
      icon: Admin
      roles:
        - admin
      description: Set up secure login credentials.
      descriptionKey: steps.setupAuthentication.description
      cta:
        text: Learn more
        textKey: steps.setupAuthentication.ctaTitle
        link: https://docs.redhat.com/en/documentation/red_hat_developer_hub/

backend:
  baseUrl: http://localhost:7007
  cors:
    origin: http://localhost:7007

Step 4: Build and start

# Build app-next (picks up app-config.yaml and app-config.local.yaml from the repo root)
EXPERIMENTAL_MODULE_FEDERATION=true yarn workspace app-next build

# Start the backend (serves the built frontend + module federation remotes)
yarn workspace backend start:next

The app-config.local.yaml must exist before building — the frontend config is baked into the bundle at build time.

The app is served at http://localhost:7007 (not port 3000 — the backend serves the built frontend directly).

Step 5: Verify with the app visualizer

Navigate to http://localhost:7007/visualizer/tree to see the NFS extension tree. Confirm these quickstart extensions are registered:

• app-root-wrapper:app/global-header → gh-menu-item:quickstart/quickstart
• app-root-wrapper:app/drawer → app-drawer-content:quickstart/quickstart
• app-root-element:app/quickstart-init
• translation:app/quickstart-translations

Backend logs to verify

The backend should log:

Exposed dynamic frontend plugin '@red-hat-developer-hub/backstage-plugin-quickstart'
/remotes => [{"packageName":"@red-hat-developer-hub/backstage-plugin-quickstart",
  "exposedModules":[".","quickstart-init-module","quickstart-translations-module"]}]

Issues

Global header not rendering visually in rhdh app-next

Symptom: The NFS extension tree (visualizer) shows app-root-wrapper:app/global-header is registered with the quickstart menu item attached, but the header bar doesn't appear visually.

Cause: The @red-hat-developer-hub/backstage-plugin-global-header package installed in the rhdh has an ESM import resolution issue with @mui/material/IconButton. The webpack build resolves this at compile time, but a runtime rendering error in the component prevents it from displaying.

Impact: The quickstart NFS plugin is correctly loaded and all extensions are properly wired in the NFS tree. The visual rendering issue is in the global-header infrastructure, not in the quickstart plugin itself.

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

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 54.03%. Comparing base (54dcf0a) to head (6c536d0).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3530      +/-   ##
==========================================
+ Coverage   54.01%   54.03%   +0.01%     
==========================================
  Files        2325     2326       +1     
  Lines       89151    89181      +30     
  Branches    24911    24912       +1     
==========================================
+ Hits        48156    48186      +30     
  Misses      40760    40760              
  Partials      235      235              

Flag	Coverage Δ		*Carryforward flag
adoption-insights	83.70% <ø> (ø)		Carriedforward from 54dcf0a
ai-integrations	67.95% <ø> (ø)		Carriedforward from 54dcf0a
app-defaults	69.79% <ø> (ø)		Carriedforward from 54dcf0a
augment	46.39% <ø> (ø)		Carriedforward from 54dcf0a
boost	74.35% <ø> (ø)		Carriedforward from 54dcf0a
bulk-import	72.46% <ø> (ø)		Carriedforward from 54dcf0a
cost-management	14.10% <ø> (ø)		Carriedforward from 54dcf0a
dcm	61.81% <ø> (ø)		Carriedforward from 54dcf0a
extensions	61.53% <ø> (ø)		Carriedforward from 54dcf0a
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from 54dcf0a
global-header	59.71% <ø> (ø)		Carriedforward from 54dcf0a
homepage	49.84% <ø> (ø)		Carriedforward from 54dcf0a
install-dynamic-plugins	56.77% <ø> (ø)		Carriedforward from 54dcf0a
konflux	91.49% <ø> (ø)		Carriedforward from 54dcf0a
lightspeed	68.54% <ø> (ø)		Carriedforward from 54dcf0a
mcp-integrations	85.46% <ø> (ø)		Carriedforward from 54dcf0a
orchestrator	37.11% <ø> (ø)		Carriedforward from 54dcf0a
quickstart	65.63% <100.00%> (+1.86%)	⬆️
sandbox	79.56% <ø> (ø)		Carriedforward from 54dcf0a
scorecard	82.67% <ø> (ø)		Carriedforward from 54dcf0a
theme	61.26% <ø> (ø)		Carriedforward from 54dcf0a
translations	7.25% <ø> (ø)		Carriedforward from 54dcf0a
x2a	78.68% <ø> (ø)		Carriedforward from 54dcf0a

*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 54dcf0a...6c536d0. 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.

[ciiay]

Thanks for the PR 👏

I have verified in both plugin NFS dev app and RHDH app-next, both works as expected.

In plugin's dev app:

In RHDH app-next app:

I'm good to merge this PR once comments from @rohitkrai03 get addressed.

[ciiay]

/lgtm

Thanks for the pr 🙌

[rohitkrai03]

/approve

[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