feat(konflux): add support for the New Frontend System (NFS)

[rrosatti]

Hey, I just made a Pull Request!

Adds NFS (New Frontend System) support to the Konflux frontend plugin, required for RHDH 2.1 compatibility.

RHDH 2.1 drops legacy frontend system support (RHIDP-15077). Without this migration, the Konflux plugin will not load in RHDH 2.1.

Fixes https://redhat.atlassian.net/browse/KFLUXUI-1558

Changes

• Added src/alpha.tsx with createFrontendPlugin and 5 NFS extensions:
  • EntityContentBlueprint for CI/CD tab (annotation: konflux-ci.dev/ci)
  • EntityContentBlueprint for Konflux tab (annotation: konflux-ci.dev/konflux)
  • EntityCardBlueprint for Latest Releases card (annotation: konflux-ci.dev/overview)
  • EntityCardBlueprint for Status card (annotation: konflux-ci.dev/overview)
• Updated package.json with exports, typesVersions, scalprum config, and @backstage/frontend-plugin-api dependency
• Legacy plugin.ts is unchanged - RHDH <2.1 continues to work via the existing entry point

Verified on local RHDH instance

Legacy system (RHDH <2.1)

rhdh-plugins-konflux-legacy.mov

New Frontend System (RHDH 2.1+)

rhdh-plugins-konflux-nfs.mov

✔️ 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
@red-hat-developer-hub/backstage-plugin-konflux	workspaces/konflux/plugins/konflux	minor	v0.1.8

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.07%. Comparing base (af4db66) to head (437bc18).
⚠️ Report is 16 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4143   +/-   ##
=======================================
  Coverage   58.07%   58.07%           
=======================================
  Files        2407     2407           
  Lines       96276    96276           
  Branches    26855    26845   -10     
=======================================
  Hits        55908    55908           
  Misses      38907    38907           
  Partials     1461     1461           

Flag	Coverage Δ		*Carryforward flag
adoption-insights	84.55% <ø> (ø)		Carriedforward from 7aff567
ai-integrations	69.71% <ø> (ø)		Carriedforward from 7aff567
app-defaults	69.79% <ø> (ø)		Carriedforward from 7aff567
augment	46.67% <ø> (ø)		Carriedforward from 7aff567
boost	76.77% <ø> (ø)		Carriedforward from 7aff567
bulk-import	72.56% <ø> (ø)		Carriedforward from 7aff567
cost-management	13.55% <ø> (ø)		Carriedforward from 7aff567
dcm	60.72% <ø> (ø)		Carriedforward from 7aff567
extensions	56.59% <ø> (ø)		Carriedforward from 7aff567
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from 7aff567
global-header	68.56% <ø> (ø)		Carriedforward from 7aff567
homepage	47.50% <ø> (ø)		Carriedforward from 7aff567
install-dynamic-plugins	59.95% <ø> (ø)		Carriedforward from 7aff567
intelligent-assistant	74.53% <ø> (ø)		Carriedforward from 7aff567
konflux	91.98% <ø> (ø)
lightspeed	69.02% <ø> (ø)		Carriedforward from 7aff567
mcp-integrations	83.40% <ø> (ø)		Carriedforward from 7aff567
orchestrator	66.85% <ø> (ø)		Carriedforward from 7aff567
quickstart	65.04% <ø> (ø)		Carriedforward from 7aff567
sandbox	79.56% <ø> (ø)		Carriedforward from 7aff567
scorecard	85.34% <ø> (ø)		Carriedforward from 7aff567
theme	88.52% <ø> (ø)		Carriedforward from 7aff567
translations	5.12% <ø> (ø)		Carriedforward from 7aff567
x2a	79.20% <ø> (ø)		Carriedforward from 7aff567

*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 af4db66...437bc18. 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]

PR Summary by Qodo

Konflux plugin: add NFS (RHDH 2.1+) alpha entrypoint

✨ Enhancement ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Add an NFS-compatible alpha entrypoint using Backstage frontend-plugin API.
• Expose entity content and card extensions gated by Konflux annotations.
• Update package exports/scalprum wiring while keeping the legacy entrypoint working.

Diagram

graph TD
  rhdhLegacy{{"RHDH <2.1"}} --> pkg["konflux package"] --> index["src/index.ts"] --> legacy["src/plugin.ts"]
  rhdhNfs{{"RHDH 2.1+ (NFS)"}} --> pkg --> alpha["src/alpha.tsx"] --> routes["src/routes.ts"] --> ext["Entity blueprints"] --> ui["Konflux UI"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Replace legacy entrypoint with NFS-only plugin

• ➕ Eliminates dual entrypoint maintenance
• ➕ Forces all consumers onto the supported frontend system
• ➖ Breaks RHDH <2.1 users immediately
• ➖ Harder migration path for downstream adopters

2. Share annotation predicates/constants between index.ts and alpha.tsx

• ➕ Avoids duplicating annotation keys and boolean checks
• ➕ Reduces drift between legacy and NFS gating behavior
• ➖ Small refactor with low immediate ROI
• ➖ Requires deciding on a stable public/shared API surface

3. Publish a separate -alpha package instead of ./alpha export

• ➕ Clear separation of stable vs alpha APIs
• ➕ Avoids conditional exports/typesVersions complexity
• ➖ More packages to version, publish, and document
• ➖ More adoption friction for consumers

Recommendation: Keep the current dual-entrypoint approach: it matches Backstage/RHDH migration patterns (legacy stays stable; NFS is introduced via an alpha export) and preserves compatibility for pre-2.1 consumers. Consider a small follow-up to centralize annotation keys/predicates to prevent drift between legacy and NFS entrypoints.

Files changed (5) +393 / -4

Enhancement (1) +91 / -0

alpha.tsxImplement NFS createFrontendPlugin with entity extensions +91/-0

Implement NFS createFrontendPlugin with entity extensions

• Adds an alpha NFS entrypoint using createFrontendPlugin and catalog-react blueprints. Registers entity content tabs and overview cards gated by Konflux annotations and lazily loads existing UI components.

workspaces/konflux/plugins/konflux/src/alpha.tsx

Documentation (1) +271 / -0

report-alpha.api.mdAdd generated alpha API report for NFS entrypoint +271/-0

Add generated alpha API report for NFS entrypoint

• Adds an API Extractor report describing the public alpha surface (frontend plugin + entity extensions) exported by the package.

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

Other (3) +31 / -4

shy-lilies-sink.mdAdd changeset for Konflux NFS alpha support +5/-0

Add changeset for Konflux NFS alpha support

• Introduces a minor-version changeset describing the new NFS (alpha) entrypoint required for RHDH 2.1 compatibility.

workspaces/konflux/.changeset/shy-lilies-sink.md

package.jsonExpose ./alpha entrypoint and scalprum modules +25/-4

Expose ./alpha entrypoint and scalprum modules

• Adds package exports and typesVersions for an alpha entrypoint, plus scalprum exposedModules for PluginRoot and Alpha. Also adds the @backstage/frontend-plugin-api dependency and removes redundant publishConfig fields when using exports.

workspaces/konflux/plugins/konflux/package.json

yarn.lockLockfile update for @backstage/frontend-plugin-api +1/-0

Lockfile update for @backstage/frontend-plugin-api

• Updates the workspace lockfile to include the newly added @backstage/frontend-plugin-api dependency.

workspaces/konflux/yarn.lock

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (0) 📘 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: 84072ae9)

  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. Frontend API version drift ✓ Resolved 🔗 Cross-repo conflict ≡ Correctness

Description

The Konflux plugin adds NFS support via createFrontendPlugin, but it depends on
@backstage/frontend-plugin-api ^0.16.0 while RHDH app-next pins 0.17.2; these ranges don’t
overlap, so RHDH will install two copies and the host may not recognize/handle the plugin instance
correctly.

Code

workspaces/konflux/plugins/konflux/package.json[R56-58]

    "@backstage/core-plugin-api": "^1.12.4",
+    "@backstage/frontend-plugin-api": "^0.16.0",
    "@backstage/plugin-catalog-react": "^2.1.1",

Relevance

●●● Strong

Repo aligns Backstage deps to avoid incompatible duplicates; NFS plugin-api drift is high-risk
integration issue.

PR-#1856
PR-#3929

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR declares @backstage/frontend-plugin-api as ^0.16.0 and uses it to create the NFS plugin; RHDH
app-next pins @backstage/frontend-plugin-api to 0.17.2, which is outside that semver range,
implying duplicate installs when Konflux is consumed by RHDH.

workspaces/konflux/plugins/konflux/package.json[53-60]
workspaces/konflux/plugins/konflux/src/alpha.tsx[17-21]
External repo: redhat-developer/rhdh, packages/app-next/package.json [49-53]
External repo: redhat-developer/rhdh, dynamic-plugins/wrappers/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic/package.json [37-39]

Agent prompt

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

### Issue description
RHDH `app-next` (NFS host) pins `@backstage/frontend-plugin-api` to `0.17.2`, but this plugin declares `^0.16.0`.

Because `^0.16.0` (0.x caret) means `>=0.16.0 <0.17.0`, it **cannot** be satisfied by `0.17.2`. When this plugin is installed into RHDH, package managers will resolve **two different versions** of `@backstage/frontend-plugin-api`, which is risky for NFS because the alpha entrypoint is created via `createFrontendPlugin`.

### Issue Context
This PR’s new `./alpha` entrypoint is intended to make the plugin load in RHDH 2.1+ (NFS). Version alignment with the host app’s Backstage packages is required to avoid duplicate instances of core framework packages.

### Fix Focus Areas
- workspaces/konflux/plugins/konflux/package.json[53-60]
- workspaces/konflux/plugins/konflux/src/alpha.tsx[17-21]
- workspaces/konflux/yarn.lock[9763-9768]

### Suggested fix
- Update `@backstage/frontend-plugin-api` to match the RHDH app-next version (e.g., `^0.17.2` or the exact version RHDH pins).
- Regenerate `yarn.lock`.
- (Optional but recommended) align other `@backstage/*` versions to the same Backstage minor line used by RHDH 2.1 to avoid similar duplication issues.

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

---

2. Catalog-react major mismatch ✓ Resolved 🔗 Cross-repo conflict ≡ Correctness

Description

Konflux still depends on @backstage/plugin-catalog-react ^2.1.1, but RHDH app-next pins 3.1.0;
these ranges don’t overlap and the plugin imports useEntity from plugin-catalog-react, which is
likely to break when rendered under RHDH’s catalog/entity provider from a different major version.

Code

workspaces/konflux/plugins/konflux/src/alpha.tsx[R18-21]

+import {
+  EntityContentBlueprint,
+  EntityCardBlueprint,
+} from '@backstage/plugin-catalog-react/alpha';

Relevance

●●● Strong

Non-overlapping major for catalog-react likely causes provider/hook mismatch; repo has precedent to
align versions.

PR-#1856
PR-#3929

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

RHDH app-next pins catalog-react 3.1.0, while Konflux depends on ^2.1.1 and calls useEntity() from
that package; the incompatible version ranges imply duplicate majors and a likely hook/provider
mismatch when running inside RHDH.

workspaces/konflux/plugins/konflux/package.json[53-60]
workspaces/konflux/plugins/konflux/src/components/KonfluxPage/KonfluxPage.tsx[19-35]
workspaces/konflux/plugins/konflux/src/alpha.tsx[18-21]
External repo: redhat-developer/rhdh, packages/app-next/package.json [56-63]

Agent prompt

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

### Issue description
RHDH `app-next` pins `@backstage/plugin-catalog-react` to `3.1.0`, but Konflux depends on `^2.1.1`.

Because `^2.1.1` does not allow `3.x`, installing this plugin into RHDH will resolve **two majors** of `@backstage/plugin-catalog-react`. Konflux uses `useEntity()` from `@backstage/plugin-catalog-react`, which commonly relies on React context provided by the host’s catalog/entity page; mixing majors frequently causes hooks/providers to mismatch.

### Issue Context
This PR adds an NFS `./alpha` entrypoint that also imports catalog-react alpha blueprints. For RHDH 2.1 compatibility, catalog-react should be aligned with the host’s pinned Backstage version set.

### Fix Focus Areas
- workspaces/konflux/plugins/konflux/package.json[53-60]
- workspaces/konflux/plugins/konflux/src/alpha.tsx[17-21]
- workspaces/konflux/plugins/konflux/src/components/KonfluxPage/KonfluxPage.tsx[19-35]

### Suggested fix
- Bump `@backstage/plugin-catalog-react` to the major/minor line used by RHDH app-next (e.g., `^3.1.0`).
- Re-test Konflux pages that use `useEntity()` and the new NFS blueprints against RHDH 2.1.
- Regenerate `yarn.lock` and address any API adjustments required by catalog-react v3.

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

---

3. Scalprum bundle not shipped ✓ Resolved 🐞 Bug ☼ Reliability

Description

workspaces/konflux/plugins/konflux/package.json adds a scalprum.exposedModules section but the
package files allowlist only includes dist and config.d.ts, so any generated dist-scalprum
output will be excluded from the published package. This breaks dynamic-plugin/scalprum consumers
that expect the scalprum build artifacts to be present alongside the exposed module metadata.

Code

workspaces/konflux/plugins/konflux/package.json[R97-103]

+  "scalprum": {
+    "name": "red-hat-developer-hub.backstage-plugin-konflux",
+    "exposedModules": {
+      "PluginRoot": "./src/index.ts",
+      "Alpha": "./src/alpha.tsx"
+    }
+  }

Relevance

●●● Strong

Missing build artifacts in npm files list is a deterministic packaging break for scalprum consumers.

PR-#3513
PR-#3943

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Konflux’s files allowlist omits dist-scalprum while the PR adds a scalprum block with exposed
modules. In contrast, other scalprum-enabled plugins in this repo (e.g., quickstart and
intelligent-assistant) explicitly include dist-scalprum in files, indicating the expected
packaging pattern for scalprum artifacts.

workspaces/konflux/plugins/konflux/package.json[92-103]
workspaces/quickstart/plugins/quickstart/package.json[103-116]
workspaces/intelligent-assistant/plugins/intelligent-assistant/package.json[112-126]

Agent prompt

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

### Issue description
`package.json` introduces a `scalprum` section (with `exposedModules`) but the package `files` allowlist does not include the scalprum build output directory. When the package is packed/published, the scalprum artifacts (commonly `dist-scalprum`) will not be included.

### Issue Context
Other scalprum-enabled frontend plugins in this repo include `dist-scalprum` in their `files` allowlist, ensuring the generated scalprum bundle is shipped.

### Fix Focus Areas
- workspaces/konflux/plugins/konflux/package.json[92-103]

ⓘ 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

[milantaky]

LGTM, verified locally:)