docs(home): update docs and app-next example for HomePageLayoutBlueprint

- Update README.md to reference HomePageLayoutBlueprint instead of
  deleted HomepageBlueprint, with a complete working example
- Update docs/getting-started/homepage.md with corrected blueprint name
- Fix app-next example to properly accept and render widgets via the
  HomePageLayoutProps interface instead of ignoring them
Signed-off-by: Adam Kunicki <kunickiaj@gmail.com>

docs/getting-started/homepage.md

@@ -92,7 +92,7 @@ app:
 
 The New Frontend System provides powerful customization options:
 
-**Custom Homepage Layouts**: Use the `HomepageBlueprint` to create custom homepage layouts with your own design and widget arrangements.
+**Custom Homepage Layouts**: Use the `HomePageLayoutBlueprint` from `@backstage/plugin-home-react/alpha` to create custom homepage layouts with your own design and widget arrangements. A layout receives the installed widgets and is responsible for rendering them. If no custom layout is installed, the plugin provides a built-in default.
 
 **Adding Homepage Widgets**: Register custom widgets using the `HomepageWidgetBlueprint` from the `@backstage/plugin-home-react/alpha` package.
 

packages/app-next/src/App.tsx

@@ -21,7 +21,18 @@ import userSettingsPlugin from '@backstage/plugin-user-settings/alpha';
 import homePlugin from '@backstage/plugin-home/alpha';
 
 import { createFrontendModule } from '@backstage/frontend-plugin-api';
-import { HomePageLayoutBlueprint } from '@backstage/plugin-home-react/alpha';
+import {
+  HomePageLayoutBlueprint,
+  type HomePageLayoutProps,
+} from '@backstage/plugin-home-react/alpha';
+import { Fragment } from 'react';
+import { Content, Header, Page } from '@backstage/core-components';
+import {
+  CustomHomepageGrid,
+  WelcomeTitle,
+  HeaderWorldClock,
+  type ClockConfig,
+} from '@backstage/plugin-home';
 import {
   techdocsPlugin,
   TechDocsIndexPage,
@@ -29,7 +40,6 @@ import {
   EntityTechdocsContent,
 } from '@backstage/plugin-techdocs';
 import appVisualizerPlugin from '@backstage/plugin-app-visualizer';
-import { homePage } from './HomePage';
 import { convertLegacyAppRoot } from '@backstage/core-compat-api';
 import { FlatRoutes } from '@backstage/core-app-api';
 import { Route } from 'react-router';
@@ -93,16 +103,36 @@ const convertedTechdocsPlugin = convertLegacyPlugin(techdocsPlugin, {
   ],
 });
 
+const clockConfigs: ClockConfig[] = [
+  { label: 'NYC', timeZone: 'America/New_York' },
+  { label: 'UTC', timeZone: 'UTC' },
+  { label: 'STO', timeZone: 'Europe/Stockholm' },
+  { label: 'TYO', timeZone: 'Asia/Tokyo' },
+];
+
 const customHomePageModule = createFrontendModule({
   pluginId: 'home',
   extensions: [
     HomePageLayoutBlueprint.make({
       params: {
         loader: async () =>
-          // This is a legacy-style home page that renders static content.
-          // In production, you'd use the widgets prop to render dynamic widgets.
-          function LegacyHomePageLayout() {
-            return homePage;
+          function CustomHomePageLayout({ widgets }: HomePageLayoutProps) {
+            return (
+              <Page themeId="home">
+                <Header title={<WelcomeTitle />} pageTitleOverride="Home">
+                  <HeaderWorldClock clockConfigs={clockConfigs} />
+                </Header>
+                <Content>
+                  <CustomHomepageGrid>
+                    {widgets.map((widget, index) => (
+                      <Fragment key={widget.name ?? index}>
+                        {widget.component}
+                      </Fragment>
+                    ))}
+                  </CustomHomepageGrid>
+                </Content>
+              </Page>
+            );
           },
       },
     }),

plugins/home/README.md

@@ -41,25 +41,51 @@ The plugin will automatically provide:
 
 #### Creating Custom Homepage Layouts
 
-Use the `HomepageBlueprint` to create custom homepage layouts:
+Use the `HomePageLayoutBlueprint` from `@backstage/plugin-home-react/alpha` to
+create custom homepage layouts. A layout receives the installed widgets and is
+responsible for arranging them on the page. If no custom layout is installed, the
+plugin provides a built-in default.
 
 ```ts
-import { HomepageBlueprint } from '@backstage/plugin-home/alpha';
+import { HomePageLayoutBlueprint } from '@backstage/plugin-home-react/alpha';
+import { CustomHomepageGrid } from '@backstage/plugin-home';
 import { Content, Header, Page } from '@backstage/core-components';
+import { Fragment } from 'react';
 
-const myHomePage = HomepageBlueprint.make({
+const myHomePageLayout = HomePageLayoutBlueprint.make({
   params: {
-    title: 'My Custom Home',
-    render: ({ grid }) => (
-      <Page themeId="home">
-        <Header title="Welcome" />
-        <Content>{grid}</Content>
-      </Page>
-    ),
+    loader: async () =>
+      function MyHomePageLayout({ widgets }) {
+        return (
+          <Page themeId="home">
+            <Header title="Welcome" />
+            <Content>
+              <CustomHomepageGrid>
+                {widgets.map((widget, index) => (
+                  <Fragment key={widget.name ?? index}>
+                    {widget.component}
+                  </Fragment>
+                ))}
+              </CustomHomepageGrid>
+            </Content>
+          </Page>
+        );
+      },
   },
 });
 ```
 
+Then register the layout in a frontend module:
+
+```ts
+import { createFrontendModule } from '@backstage/frontend-plugin-api';
+
+const homeModule = createFrontendModule({
+  pluginId: 'home',
+  extensions: [myHomePageLayout],
+});
+```
+
 #### Visit Tracking (Optional)
 
 Visit tracking is an **optional feature** that must be explicitly enabled. When enabled, it provides intelligent storage fallbacks: