fix(homepage): return optional response when no default widgets are configured (#3137)

When no `homepage.defaultWidgets` config is set, return an empty response
instead of an empty items array, allowing the frontend to distinguish
"unconfigured" from "configured but all filtered out."

Signed-off-by: Christoph Jerolimov <jerolimov+git@redhat.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: christoph-jerolimov

workspaces/homepage/.changeset/forty-peas-dress.md

@@ -0,0 +1,6 @@
+---
+'@red-hat-developer-hub/backstage-plugin-homepage-backend': patch
+'@red-hat-developer-hub/backstage-plugin-homepage-common': patch
+---
+
+Make default widgets response optional when no widgets are configured, so that no widget is shown when no conditional widget can be shown.

workspaces/homepage/plugins/homepage-backend/src/defaultWidgets/loadDefaultWidgets.test.ts

@@ -22,9 +22,9 @@ import {
 import { DefaultWidgetNode } from './types';
 
 describe('loadDefaultWidgets', () => {
-  it('returns an empty array when homepage.defaultWidgets is absent', () => {
+  it('returns undefined when homepage.defaultWidgets is absent', () => {
     const config = mockServices.rootConfig({ data: {} });
-    expect(loadDefaultWidgets(config)).toEqual([]);
+    expect(loadDefaultWidgets(config)).toBeUndefined();
   });
 
   it('parses a valid tree', () => {

workspaces/homepage/plugins/homepage-backend/src/defaultWidgets/loadDefaultWidgets.ts

@@ -75,9 +75,9 @@ export const defaultWidgetsSchema = z.array(defaultWidgetNodeSchema);
  */
 export function loadDefaultWidgets(
   config: RootConfigService,
-): DefaultWidgetNode[] {
+): DefaultWidgetNode[] | undefined {
   const raw = config.getOptional('homepage.defaultWidgets');
-  if (raw === undefined) return [];
+  if (raw === undefined) return undefined;
   const parsed = defaultWidgetsSchema.safeParse(raw);
   if (!parsed.success) {
     throw new Error(

workspaces/homepage/plugins/homepage-backend/src/plugin.test.ts

@@ -147,15 +147,15 @@ describe('homepagePlugin', () => {
     });
   });
 
-  it('returns an empty list when no default widgets are configured', async () => {
+  it('returns no items when no default widgets are configured', async () => {
     const { server } = await startTestBackend({
       features: [homepagePlugin],
     });
 
     const res = await request(server).get('/api/homepage/default-widgets');
 
     expect(res.status).toBe(200);
-    expect(res.body).toEqual({ items: [] });
+    expect(res.body).toEqual({});
   });
 
   it('rejects unauthenticated requests', async () => {

workspaces/homepage/plugins/homepage-backend/src/services/DefaultWidgetsService.ts

@@ -43,7 +43,7 @@ export interface DefaultWidgetsService {
 }
 
 export class DefaultWidgetsServiceImpl implements DefaultWidgetsService {
-  readonly #tree: DefaultWidgetNode[];
+  readonly #tree: DefaultWidgetNode[] | undefined;
   readonly #referencedPermissions: Set<string>;
   readonly #catalog: typeof catalogServiceRef.T;
   readonly #permissions: PermissionsService;
@@ -56,10 +56,14 @@ export class DefaultWidgetsServiceImpl implements DefaultWidgetsService {
     logger: LoggerService;
   }): DefaultWidgetsServiceImpl {
     const tree = loadDefaultWidgets(options.config);
-    const referencedPermissions = collectReferencedPermissions(tree);
-    options.logger.info(
-      `Loaded ${tree.length} default homepage card root node(s) referencing ${referencedPermissions.size} permission(s)`,
-    );
+    const referencedPermissions = collectReferencedPermissions(tree ?? []);
+    if (tree) {
+      options.logger.info(
+        `Loaded ${tree.length} default homepage card root node(s) referencing ${referencedPermissions.size} permission(s)`,
+      );
+    } else {
+      options.logger.info('No default homepage widgets configured');
+    }
     return new DefaultWidgetsServiceImpl(
       tree,
       referencedPermissions,
@@ -70,7 +74,7 @@ export class DefaultWidgetsServiceImpl implements DefaultWidgetsService {
   }
 
   private constructor(
-    tree: DefaultWidgetNode[],
+    tree: DefaultWidgetNode[] | undefined,
     referencedPermissions: Set<string>,
     catalog: typeof catalogServiceRef.T,
     permissions: PermissionsService,
@@ -88,6 +92,9 @@ export class DefaultWidgetsServiceImpl implements DefaultWidgetsService {
   }: {
     credentials: BackstageCredentials<BackstageUserPrincipal>;
   }): Promise<DefaultWidgetsResponse> {
+    if (!this.#tree) {
+      return {};
+    }
     const ctx = await buildUserContext({
       credentials,
       catalog: this.#catalog,

workspaces/homepage/plugins/homepage-common/report.api.md

@@ -24,7 +24,7 @@ export interface DefaultWidgetNode {
 // @public (undocumented)
 export interface DefaultWidgetsResponse {
   // (undocumented)
-  items: VisibleDefaultWidget[];
+  items?: VisibleDefaultWidget[];
 }
 
 // @public (undocumented)

workspaces/homepage/plugins/homepage-common/src/types.ts

@@ -49,5 +49,5 @@ export interface VisibleDefaultWidget {
  * @public
  */
 export interface DefaultWidgetsResponse {
-  items: VisibleDefaultWidget[];
+  items?: VisibleDefaultWidget[];
 }