From 929c55adbc7095a6431512cbb37a22513b94062c Mon Sep 17 00:00:00 2001
From: Shijun Wang <shijun@shijun.dev>
Date: Mon, 8 Sep 2025 15:07:15 +0300
Subject: [PATCH 1/2] wait for storage to become ready

Signed-off-by: Shijun Wang <shijun@shijun.dev>
---
 .changeset/heavy-cats-unite.md                     |  6 ++++++
 plugins/home/report.api.md                         |  2 +-
 .../CustomHomepage/CustomHomepageGrid.tsx          | 14 +++++++++++---
 3 files changed, 18 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/heavy-cats-unite.md

diff --git a/.changeset/heavy-cats-unite.md b/.changeset/heavy-cats-unite.md
new file mode 100644
index 0000000000..4875093b0a
--- /dev/null
+++ b/.changeset/heavy-cats-unite.md
@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-home': patch
+---
+
+Fixed race condition in CustomHomepageGrid by waiting for storage to load before rendering custom layout to prevent
+rendering of the default content.
diff --git a/plugins/home/report.api.md b/plugins/home/report.api.md
index dd33b952ee..73c6d035cc 100644
--- a/plugins/home/report.api.md
+++ b/plugins/home/report.api.md
@@ -84,7 +84,7 @@ export const createCardExtension: typeof createCardExtension_2;
 // @public
 export const CustomHomepageGrid: (
   props: CustomHomepageGridProps,
-) => JSX_2.Element;
+) => JSX_2.Element | null;
 
 // @public
 export type CustomHomepageGridProps = {
diff --git a/plugins/home/src/components/CustomHomepage/CustomHomepageGrid.tsx b/plugins/home/src/components/CustomHomepage/CustomHomepageGrid.tsx
index 5d85e834e8..b4b674be1b 100644
--- a/plugins/home/src/components/CustomHomepage/CustomHomepageGrid.tsx
+++ b/plugins/home/src/components/CustomHomepage/CustomHomepageGrid.tsx
@@ -90,7 +90,7 @@ const useStyles = makeStyles((theme: Theme) =>
 
 function useHomeStorage(
   defaultWidgets: GridWidget[],
-): [GridWidget[], (value: GridWidget[]) => void] {
+): [GridWidget[], (value: GridWidget[]) => void, boolean] {
   const key = 'home';
   const storageApi = useApi(storageApiRef).forBucket('home.customHomepage');
   // TODO: Support multiple home pages
@@ -110,6 +110,9 @@ function useHomeStorage(
     storageApi.observe$<string>(key),
     storageApi.snapshot(key),
   );
+
+  const isStorageLoading = homeSnapshot.presence === 'unknown' || !homeSnapshot;
+
   const widgets: GridWidget[] = useMemo(() => {
     if (homeSnapshot.presence === 'absent') {
       return defaultWidgets;
@@ -122,7 +125,7 @@ function useHomeStorage(
     }
   }, [homeSnapshot, defaultWidgets]);
 
-  return [widgets, setWidgets];
+  return [widgets, setWidgets, isStorageLoading];
 }
 
 const convertConfigToDefaultWidgets = (
@@ -213,7 +216,7 @@ export const CustomHomepageGrid = (props: CustomHomepageGridProps) => {
       ? convertConfigToDefaultWidgets(props.config, availableWidgets)
       : [];
   }, [props.config, availableWidgets]);
-  const [widgets, setWidgets] = useHomeStorage(defaultLayout);
+  const [widgets, setWidgets, isStorageLoading] = useHomeStorage(defaultLayout);
   const [addWidgetDialogOpen, setAddWidgetDialogOpen] = useState(false);
   const editModeOn = widgets.find(w => w.layout.isResizable) !== undefined;
   const [editMode, setEditMode] = useState(editModeOn);
@@ -322,6 +325,11 @@ export const CustomHomepageGrid = (props: CustomHomepageGridProps) => {
     );
   };
 
+  // Don't render anything while storage is loading
+  if (isStorageLoading) {
+    return null;
+  }
+
   return (
     <>
       <ContentHeader title={props.title}>

From a2be46e16b8f820fae952e149cb69afe3e20527d Mon Sep 17 00:00:00 2001
From: Shijun Wang <shijun@shijun.dev>
Date: Tue, 9 Sep 2025 08:33:25 +0300
Subject: [PATCH 2/2] return progress bar instead of null

Signed-off-by: Shijun Wang <shijun@shijun.dev>
---
 plugins/home/report.api.md                               | 2 +-
 .../src/components/CustomHomepage/CustomHomepageGrid.tsx | 9 ++++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/plugins/home/report.api.md b/plugins/home/report.api.md
index 73c6d035cc..dd33b952ee 100644
--- a/plugins/home/report.api.md
+++ b/plugins/home/report.api.md
@@ -84,7 +84,7 @@ export const createCardExtension: typeof createCardExtension_2;
 // @public
 export const CustomHomepageGrid: (
   props: CustomHomepageGridProps,
-) => JSX_2.Element | null;
+) => JSX_2.Element;
 
 // @public
 export type CustomHomepageGridProps = {
diff --git a/plugins/home/src/components/CustomHomepage/CustomHomepageGrid.tsx b/plugins/home/src/components/CustomHomepage/CustomHomepageGrid.tsx
index b4b674be1b..fec7895170 100644
--- a/plugins/home/src/components/CustomHomepage/CustomHomepageGrid.tsx
+++ b/plugins/home/src/components/CustomHomepage/CustomHomepageGrid.tsx
@@ -34,7 +34,11 @@ import {
 } from '@material-ui/core/styles';
 import { compact } from 'lodash';
 import useObservable from 'react-use/esm/useObservable';
-import { ContentHeader, ErrorBoundary } from '@backstage/core-components';
+import {
+  ContentHeader,
+  ErrorBoundary,
+  Progress,
+} from '@backstage/core-components';
 import Typography from '@material-ui/core/Typography';
 import { WidgetSettingsOverlay } from './WidgetSettingsOverlay';
 import { AddWidgetDialog } from './AddWidgetDialog';
@@ -325,9 +329,8 @@ export const CustomHomepageGrid = (props: CustomHomepageGridProps) => {
     );
   };
 
-  // Don't render anything while storage is loading
   if (isStorageLoading) {
-    return null;
+    return <Progress />;
   }
 
   return (