feat(app-defaults): add empty state overrides for catalog pages

[christoph-jerolimov]

Summary

• Override page extensions for catalog, scaffolder (templates sub-page), API docs, TechDocs, and catalog graph plugins with an EmptyCatalogGate that checks whether matching entities exist before rendering the original page
• When no entities are found, a translatable empty state with a background illustration, action link, and support button is shown
• A FrontendFeatureLoader default export registers all overrides alongside the existing appDefaultsModule so a single package import loads everything
• Translations provided for en (default), de, es, fr, it, and ja

Test plan

• TypeScript compiles cleanly
• ESLint passes
• 11 unit tests pass (useCatalogEntities + EmptyCatalogGate)
• Verify empty state renders on /catalog when no entities are registered
• Verify original page renders on /catalog when entities exist
• Verify /create, /api-docs, /docs, /catalog-graph show empty states appropriately
• Verify scaffolder sub-pages (actions, editor, tasks) remain accessible

Ref: RHIDP-14871

🤖 Generated with Claude Code

[rhdh-gh-app]

Missing Changesets

The following package(s) are changed by this PR but do not have a changeset:

• @red-hat-developer-hub/backstage-plugin-app-defaults

See CONTRIBUTING.md for more information about how to add changesets.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
app	workspaces/app-defaults/packages/app	none	v0.0.0
@red-hat-developer-hub/backstage-plugin-app-defaults	workspaces/app-defaults/plugins/app-defaults	none	v0.1.0

[codecov]

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

[rhdh-qodo-merge]

PR Summary by Qodo

Add empty-state overrides for catalog-related pages via app-defaults loader

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

AI Description

• Wrap catalog-driven pages with EmptyCatalogGate to show an empty state when no entities exist.
• Add shared empty-state UI (illustration, action slot, support link) with translations
 (en/de/es/fr/it/ja).
• Export a default FrontendFeatureLoader to register app defaults plus all overrides in one import.

Diagram

graph TD
  A["App (createApp)"] --> B["app-defaults loader"] --> C["Plugin overrides"] --> D["Custom pages"] --> E["EmptyCatalogGate"] --> F[("Catalog API")]
  E --> G["EmptyState UI"]

  subgraph Legend
    direction LR
    _mod["Module"] ~~~ _ui["UI wrapper"] ~~~ _api[("API")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Use getEntities(limit=1) instead of facets for presence checks

• ➕ Simpler semantic model: fetch a single entity to determine non-emptiness.
• ➕ Avoids dependence on facet response shape/availability in some setups.
• ➖ May be more expensive than facets (even with limit=1).
• ➖ Requires consistent handling of filters/paging across Backstage versions.

2. Centralize gating at the routing layer (single wrapper route)

• ➕ One place to implement gating and empty-state rendering for multiple routes.
• ➕ Potential to share a cached presence result across pages.
• ➖ Harder to apply different filters per page (API vs Template vs TechDocs annotation).
• ➖ Less aligned with the extension-override mechanism used by the frontend system.

3. Make empty-state content/config fully configurable via extension config

• ➕ Downstream apps can customize text/actions/support URL without code changes.
• ➕ Better long-term flexibility for different deployments.
• ➖ Adds schema/versioning and documentation overhead.
• ➖ More moving parts than needed for an 'app defaults' package.

Recommendation: The chosen approach (override specific page/sub-page extensions and wrap the original react element with EmptyCatalogGate) is well-aligned with Backstage’s frontend plugin override model and keeps per-page filters explicit. If performance becomes a concern, consider caching presence checks per filter to avoid repeated facet calls when navigating between gated pages.

Files changed (30) +4108 / -32

Enhancement (16) +698 / -2

CustomApiDocsPage.tsxAdd API docs page wrapper with empty-state gating +43/-0

Add API docs page wrapper with empty-state gating

• Wraps the API docs page with EmptyCatalogGate filtered to kind=API and supplies translated empty-state content with a primary action link.

workspaces/app-defaults/plugins/app-defaults/src/api-docs/CustomApiDocsPage.tsx

apiDocsPluginOverride.tsxOverride API docs page extension to inject the wrapper +42/-0

Override API docs page extension to inject the wrapper

• Overrides the api-docs page extension’s react element, wrapping the original page with CustomApiDocsPage.

workspaces/app-defaults/plugins/app-defaults/src/api-docs/apiDocsPluginOverride.tsx

CustomCatalogGraphPage.tsxAdd catalog graph page wrapper with empty-state gating +42/-0

Add catalog graph page wrapper with empty-state gating

• Wraps the catalog graph page with EmptyCatalogGate and provides translated empty-state text plus a navigation action back to the catalog.

workspaces/app-defaults/plugins/app-defaults/src/catalog-graph/CustomCatalogGraphPage.tsx

catalogGraphPluginOverride.tsxOverride catalog-graph page extension to inject the wrapper +42/-0

Override catalog-graph page extension to inject the wrapper

• Overrides page:catalog-graph to wrap the original element with CustomCatalogGraphPage.

workspaces/app-defaults/plugins/app-defaults/src/catalog-graph/catalogGraphPluginOverride.tsx

CustomCatalogPage.tsxAdd catalog page wrapper with translated empty state +42/-0

Add catalog page wrapper with translated empty state

• Wraps the catalog landing page with EmptyCatalogGate and provides localized empty-state copy plus a primary link to /catalog-import.

workspaces/app-defaults/plugins/app-defaults/src/catalog/CustomCatalogPage.tsx

EmptyCatalogGate.tsxIntroduce EmptyCatalogGate component for conditional page rendering +63/-0

Introduce EmptyCatalogGate component for conditional page rendering

• Adds a gate component that shows a spinner while loading, ErrorPanel on API failure, EmptyState when no matching entities exist, and children when entities are present.

workspaces/app-defaults/plugins/app-defaults/src/catalog/EmptyCatalogGate.tsx

catalogPluginOverride.tsxOverride catalog page extension to add empty-state wrapper +42/-0

Override catalog page extension to add empty-state wrapper

• Overrides page:catalog to replace the original react element with a CustomCatalogPage-wrapped element.

workspaces/app-defaults/plugins/app-defaults/src/catalog/catalogPluginOverride.tsx

useCatalogEntities.tsAdd hook to detect entity presence via catalog facets +48/-0

Add hook to detect entity presence via catalog facets

• Implements a small hook that calls getEntityFacets with an optional filter and returns a typed loading/success/error state with hasEntities.

workspaces/app-defaults/plugins/app-defaults/src/catalog/useCatalogEntities.ts

EmptyState.tsxAdd shared EmptyState component with illustration and actions +74/-0

Add shared EmptyState component with illustration and actions

• Introduces a reusable empty state layout with title/description, optional action area, SupportButton, and a background illustration.

workspaces/app-defaults/plugins/app-defaults/src/components/empty-state/EmptyState.tsx

SupportButton.tsxAdd SupportButton that uses config-backed support URL +37/-0

Add SupportButton that uses config-backed support URL

• Adds a support link button that uses an optional prop, falls back to app.support.url config, then defaults to Red Hat Developer Hub documentation.

workspaces/app-defaults/plugins/app-defaults/src/components/empty-state/SupportButton.tsx

notfound.pngAdd empty-state illustration asset +0/-0

Add empty-state illustration asset

• Adds the PNG used as the background illustration in EmptyState.

workspaces/app-defaults/plugins/app-defaults/src/components/empty-state/notfound.png

CustomDocsPage.tsxAdd TechDocs page wrapper gated by TechDocs annotation existence +52/-0

Add TechDocs page wrapper gated by TechDocs annotation existence

• Wraps the TechDocs landing page with EmptyCatalogGate using an annotation-exists filter and provides translated empty-state content with an external 'Learn more' link.

workspaces/app-defaults/plugins/app-defaults/src/docs/CustomDocsPage.tsx

docsPluginOverride.tsxOverride TechDocs page extension to inject the wrapper +42/-0

Override TechDocs page extension to inject the wrapper

• Overrides page:techdocs to wrap the original element with CustomDocsPage.

workspaces/app-defaults/plugins/app-defaults/src/docs/docsPluginOverride.tsx

index.tsExport overrides and default feature loader for one-shot registration +39/-2

Export overrides and default feature loader for one-shot registration

• Adds named exports for each override and changes the default export to a FrontendFeatureLoader that returns appDefaultsModule plus all new overrides.

workspaces/app-defaults/plugins/app-defaults/src/index.ts

CustomScaffolderPage.tsxAdd scaffolder templates wrapper gated by Template entities +43/-0

Add scaffolder templates wrapper gated by Template entities

• Wraps the scaffolder templates sub-page with EmptyCatalogGate filtered to kind=Template and provides translated empty-state content with a catalog import action.

workspaces/app-defaults/plugins/app-defaults/src/scaffolder/CustomScaffolderPage.tsx

scaffolderPluginOverride.tsxOverride scaffolder templates sub-page while preserving other sub-pages +47/-0

Override scaffolder templates sub-page while preserving other sub-pages

• Overrides sub-page:scaffolder/templates to apply the empty-state wrapper and explicitly re-adds other scaffolder sub-page extensions to keep ordering and accessibility.

workspaces/app-defaults/plugins/app-defaults/src/scaffolder/scaffolderPluginOverride.tsx

Tests (2) +296 / -0

EmptyCatalogGate.test.tsxAdd unit tests for EmptyCatalogGate states and filtering +165/-0

Add unit tests for EmptyCatalogGate states and filtering

• Tests loading, empty, success, filter passthrough, and error behavior using a mocked catalog API and a mocked EmptyState component.

workspaces/app-defaults/plugins/app-defaults/src/catalog/EmptyCatalogGate.test.tsx

useCatalogEntities.test.tsAdd unit tests for useCatalogEntities hook +131/-0

Add unit tests for useCatalogEntities hook

• Validates initial loading state, success/empty detection from facet counts, filter passthrough, and error propagation.

workspaces/app-defaults/plugins/app-defaults/src/catalog/useCatalogEntities.test.ts

Documentation (8) +3087 / -19

report-alpha.api.mdUpdate generated app-auth alpha API report +16/-16

Update generated app-auth alpha API report

• Regenerates the API Extractor report output for app-auth (primarily ordering/normalization of exported translation key typings).

workspaces/app-defaults/plugins/app-auth/report-alpha.api.md

report.api.mdRegenerate app-defaults API report for new exports +2769/-3

Regenerate app-defaults API report for new exports

• Regenerates the API Extractor report to include the new default feature loader and the named plugin override exports.

workspaces/app-defaults/plugins/app-defaults/report.api.md

de.tsAdd German empty-state translations +47/-0

Add German empty-state translations

• Adds de messages for catalog, catalog graph, scaffolder, API docs, and TechDocs empty states.

workspaces/app-defaults/plugins/app-defaults/src/translations/de.ts

es.tsAdd Spanish empty-state translations +48/-0

Add Spanish empty-state translations

• Adds es messages for catalog, catalog graph, scaffolder, API docs, and TechDocs empty states.

workspaces/app-defaults/plugins/app-defaults/src/translations/es.ts

fr.tsAdd French empty-state translations +47/-0

Add French empty-state translations

• Adds fr messages for catalog, catalog graph, scaffolder, API docs, and TechDocs empty states.

workspaces/app-defaults/plugins/app-defaults/src/translations/fr.ts

it.tsAdd Italian empty-state translations +47/-0

Add Italian empty-state translations

• Adds it messages for catalog, catalog graph, scaffolder, API docs, and TechDocs empty states.

workspaces/app-defaults/plugins/app-defaults/src/translations/it.ts

ja.tsAdd Japanese empty-state translations +47/-0

Add Japanese empty-state translations

• Adds ja messages for catalog, catalog graph, scaffolder, API docs, and TechDocs empty states.

workspaces/app-defaults/plugins/app-defaults/src/translations/ja.ts

ref.tsDefine translationRef and default (English) empty-state messages +66/-0

Define translationRef and default (English) empty-state messages

• Adds the translation reference and default message set for all empty-state variants (catalog, catalog graph, scaffolder, API docs, TechDocs).

workspaces/app-defaults/plugins/app-defaults/src/translations/ref.ts

Other (4) +27 / -11

package.jsonAdd app-defaults workspace dependency to the app package +1/-0

Add app-defaults workspace dependency to the app package

• Adds @red-hat-developer-hub/backstage-plugin-app-defaults as a dependency so the app can load defaults/overrides from a single package import.

workspaces/app-defaults/packages/app/package.json

App.tsxRemove direct catalog/scaffolder and some app-react feature registrations +0/-10

Remove direct catalog/scaffolder and some app-react feature registrations

• Stops importing and registering catalog/scaffolder alpha plugins (and selected app-react modules) directly in the app feature list, shifting responsibility to centralized loaders/modules.

workspaces/app-defaults/packages/app/src/App.tsx

package.jsonAdd runtime dependencies required for page overrides and empty states +12/-0

Add runtime dependencies required for page overrides and empty states

• Introduces dependencies on catalog/client, core UI components, and the affected plugins (catalog, scaffolder, api-docs, techdocs, catalog-graph) to support extension overrides and gating.

workspaces/app-defaults/plugins/app-defaults/package.json

yarn.lockUpdate lockfile for new dependencies and workspace links +14/-1

Update lockfile for new dependencies and workspace links

• Updates yarn.lock to reflect the added app-defaults dependencies and the app package’s new workspace dependency on app-defaults.

workspaces/app-defaults/yarn.lock

[rhdh-qodo-merge]

Code Review by Qodo

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

1. App missing core features 🐞 Bug ≡ Correctness

Description

workspaces/app-defaults/packages/app/src/App.tsx removes catalog/scaffolder/app-react modules from
createApp(features) but never adds the new @red-hat-developer-hub/backstage-plugin-app-defaults
default feature loader, so routes/extensions provided by those plugins won’t be registered in this
app.

Code

workspaces/app-defaults/packages/app/src/App.tsx[L36-37]

-    catalogPlugin,
-    scaffolderPlugin,

Relevance

●●● Strong

Feature-loader omission directly conflicts with the PR’s stated single-import registration intent;
similar app-react export integration was accepted.

PR-#4081

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The app’s createApp(features) list no longer includes catalog/scaffolder or app-drawer/template-card
features, and there is no replacement feature/loader added despite the package dependency being
introduced. Other NFS apps explicitly register plugins in createApp(features), demonstrating these
don’t get auto-included.

workspaces/app-defaults/packages/app/src/App.tsx[17-38]
workspaces/app-defaults/packages/app/package.json[37-56]
workspaces/app-defaults/plugins/app-defaults/src/index.ts[23-61]
workspaces/adoption-insights/packages/app/src/App.tsx[16-36]
workspaces/app-defaults/plugins/app-defaults/src/appDefaultsModule.ts[17-34]

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 app-defaults example app no longer registers catalog/scaffolder (and app-react drawer/template-card) features because they were removed from the features array and not replaced with the new aggregated feature loader.

### Issue Context
This PR adds a default export feature loader in `@red-hat-developer-hub/backstage-plugin-app-defaults` that is intended to register `appDefaultsModule` and the plugin overrides. The example app removed the old direct plugin registrations but did not add the new loader.

### Fix Focus Areas
- workspaces/app-defaults/packages/app/src/App.tsx[17-38]
- workspaces/app-defaults/plugins/app-defaults/src/index.ts[23-62]
- workspaces/app-defaults/packages/app/package.json[44-55]

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

---

2. Symbol filters break hook deps 🐞 Bug ≡ Correctness

Description

useCatalogEntities uses JSON.stringify(filter) in its effect dependencies, but EntityFilterQuery
values can be symbols (e.g., CATALOG_FILTER_EXISTS), which JSON.stringify drops—so filter changes
involving symbol-based filters won’t trigger a refetch and can produce stale hasEntities results.

Code

workspaces/app-defaults/plugins/app-defaults/src/catalog/useCatalogEntities.ts[R43-45]

+      .catch(err => setState({ status: 'error', error: err }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [catalogApi, JSON.stringify(filter)]);

Relevance

●●● Strong

JSON.stringify drops symbol-valued filters, creating a deterministic stale-data bug; concrete
correctness fixes are typically accepted.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The hook’s dependency key is derived from JSON.stringify(filter). The PR passes
CATALOG_FILTER_EXISTS as a filter value, and elsewhere in the repo CATALOG_FILTER_EXISTS is
explicitly typed/used as a symbol-capable filter value, meaning JSON.stringify will not reliably
represent it.

workspaces/app-defaults/plugins/app-defaults/src/catalog/useCatalogEntities.ts[17-46]
workspaces/app-defaults/plugins/app-defaults/src/docs/CustomDocsPage.tsx[27-34]
workspaces/scorecard/plugins/scorecard-backend-module-jira/src/metricProviders/JiraOpenIssuesProvider.ts[55-59]

Agent prompt

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

### Issue description
`useCatalogEntities` uses `JSON.stringify(filter)` to detect filter changes, but symbol-valued filters (e.g. `CATALOG_FILTER_EXISTS`) are omitted during JSON serialization. This makes the dependency key incorrect and can prevent the hook from refetching when the filter changes.

### Issue Context
The PR itself uses `CATALOG_FILTER_EXISTS` in `CustomDocsPage` filters.

### Fix Focus Areas
- workspaces/app-defaults/plugins/app-defaults/src/catalog/useCatalogEntities.ts[17-46]
- workspaces/app-defaults/plugins/app-defaults/src/docs/CustomDocsPage.tsx[27-34]

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

---

3. Async setState after unmount 🐞 Bug ☼ Reliability

Description

useCatalogEntities does not cancel/guard its getEntityFacets promise, so navigating away can still
call setState on an unmounted component, causing React warnings and flaky behavior under rapid route
changes.

Code

workspaces/app-defaults/plugins/app-defaults/src/catalog/useCatalogEntities.ts[R31-43]

+  useEffect(() => {
+    catalogApi
+      .getEntityFacets({
+        facets: ['kind'],
+        filter,
+      })
+      .then(response => {
+        setState({
+          status: 'success',
+          hasEntities: response.facets.kind.some(f => f.count > 0),
+        });
+      })
+      .catch(err => setState({ status: 'error', error: err }));

Relevance

●●● Strong

Unmounted async state updates are a concrete reliability issue, and recent accepted history favors
fixing asynchronous lifecycle hazards.

PR-#4172

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The effect starts an async request and always calls setState in the promise handlers, but there is
no cleanup function returned from useEffect to prevent updates after unmount.

workspaces/app-defaults/plugins/app-defaults/src/catalog/useCatalogEntities.ts[31-46]

Agent prompt

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

### Issue description
`useCatalogEntities` performs an async call and unconditionally calls `setState` in `.then/.catch`. Without a cancellation/ignore flag in the effect cleanup, it can update state after unmount.

### Issue Context
This hook is used as a page gate; users can navigate between pages quickly, especially during initial app setup.

### Fix Focus Areas
- workspaces/app-defaults/plugins/app-defaults/src/catalog/useCatalogEntities.ts[31-46]

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

---

4. Translations not loadable 🐞 Bug ≡ Correctness

Description

Non-English translation bundles (de/es/fr/it/ja) are added but are not exported or registered by any
TranslationBlueprint/module, and the package export map only exposes the root entrypoint, making
these translations inaccessible to consumers at runtime.

Code

workspaces/app-defaults/plugins/app-defaults/src/index.ts[R51-60]

+export default createFrontendFeatureLoader({
+  loader() {
+    return [
+      appDefaultsModule,
+      catalogPluginOverride,
+      catalogGraphPluginOverride,
+      scaffolderPluginOverride,
+      apiDocsPluginOverride,
+      docsPluginOverride,
+    ];

Relevance

●● Moderate

Translation exposure is a package-integration concern, but available history supports translation
cleanup without proving this exact registration model.

PR-#4172

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The package only exports ./src/index.ts, and index.ts does not export any translation
resources/modules. At the same time, language-specific translation message files exist, but nothing
in the exported surface registers or exposes them.

workspaces/app-defaults/plugins/app-defaults/package.json[6-11]
workspaces/app-defaults/plugins/app-defaults/src/index.ts[23-61]
workspaces/app-defaults/plugins/app-defaults/src/translations/de.ts[17-47]

Agent prompt

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

### Issue description
Translation message files for multiple languages exist, but they are neither exported from the package entrypoint nor registered via a translation module/blueprint. With the package `exports` map only exposing `.`, consumers also can't deep-import these files.

### Issue Context
Other plugins in this repo register translations via `TranslationBlueprint` inside an `app`-scoped frontend module.

### Fix Focus Areas
- workspaces/app-defaults/plugins/app-defaults/src/index.ts[23-62]
- workspaces/app-defaults/plugins/app-defaults/package.json[6-11]
- workspaces/app-defaults/plugins/app-defaults/src/translations/de.ts[17-47]

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

---

5. README default export outdated 🐞 Bug ⚙ Maintainability

Description

The plugin’s README claims the default export is a FrontendModule, but this PR changes the default
export to a FrontendFeatureLoader, which will mislead consumers integrating dynamic loading.

Code

workspaces/app-defaults/plugins/app-defaults/src/index.ts[R51-52]

+export default createFrontendFeatureLoader({
+  loader() {

Relevance

●●● Strong

README contradicts the changed public default export; recent history shows reviewers accept
documentation updates for public API changes.

PR-#4316

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

README explicitly describes the default export as a FrontendModule, while the current index.ts
default export is a createFrontendFeatureLoader result.

workspaces/app-defaults/plugins/app-defaults/README.md[5-8]
workspaces/app-defaults/plugins/app-defaults/src/index.ts[44-62]

Agent prompt

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

### Issue description
README documentation no longer matches the actual default export type.

### Issue Context
Default export changed from `appDefaultsModule` to `createFrontendFeatureLoader(...)`.

### Fix Focus Areas
- workspaces/app-defaults/plugins/app-defaults/README.md[5-8]
- workspaces/app-defaults/plugins/app-defaults/src/index.ts[44-62]

ⓘ 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: 1f6ef14c)

  Explored: repo: redhat-developer/rhdh-local (sha: d74dcd51)

Tip of the day

💡 Did you know, you can switch off images and animations for a plain-text comment

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[sonarqubecloud]

Quality Gate passed

Issues
6 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