From e4544fb7732695a178dd2ba86fc7e562a0ef0667 Mon Sep 17 00:00:00 2001 From: Adam Kunicki Date: Sat, 7 Feb 2026 05:11:35 -0800 Subject: [PATCH] refactor(home): rename HomepageWidgetBlueprint to HomePageWidgetBlueprint Align naming convention with HomePageLayoutBlueprint and the catalog plugin's consistent entity- prefix pattern. Also update the kind string from 'home-widget' to 'home-page-widget' to match 'home-page-layout'. Added interface-level JSDoc to HomePageWidgetBlueprintParams. Signed-off-by: Adam Kunicki --- docs/getting-started/homepage.md | 2 +- plugins/home-react/report-alpha.api.md | 10 +++++----- plugins/home-react/src/alpha.ts | 6 +++--- ...etBlueprint.tsx => HomePageWidgetBlueprint.tsx} | 14 +++++++++----- plugins/home/README.md | 8 ++++---- plugins/home/dev/index.tsx | 8 ++++---- 6 files changed, 26 insertions(+), 22 deletions(-) rename plugins/home-react/src/alpha/blueprints/{HomepageWidgetBlueprint.tsx => HomePageWidgetBlueprint.tsx} (91%) diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md index aac8408797..65b866414b 100644 --- a/docs/getting-started/homepage.md +++ b/docs/getting-started/homepage.md @@ -94,7 +94,7 @@ The New Frontend System provides powerful customization options: **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. +**Adding Homepage Widgets**: Register custom widgets using the `HomePageWidgetBlueprint` from the `@backstage/plugin-home-react/alpha` package. For detailed instructions on creating custom layouts, registering widgets, and advanced configuration options, see the [Home plugin documentation](https://github.com/backstage/backstage/tree/master/plugins/home#readme). diff --git a/plugins/home-react/report-alpha.api.md b/plugins/home-react/report-alpha.api.md index 0fc6360e35..cd672719b1 100644 --- a/plugins/home-react/report-alpha.api.md +++ b/plugins/home-react/report-alpha.api.md @@ -79,9 +79,9 @@ export interface HomePageLayoutProps { } // @alpha -export const HomepageWidgetBlueprint: ExtensionBlueprint<{ - kind: 'home-widget'; - params: HomepageWidgetBlueprintParams; +export const HomePageWidgetBlueprint: ExtensionBlueprint<{ + kind: 'home-page-widget'; + params: HomePageWidgetBlueprintParams; output: ExtensionDataRef; inputs: {}; config: {}; @@ -95,8 +95,8 @@ export const HomepageWidgetBlueprint: ExtensionBlueprint<{ }; }>; -// @alpha (undocumented) -export interface HomepageWidgetBlueprintParams { +// @alpha +export interface HomePageWidgetBlueprintParams { componentProps?: Record; components: () => Promise; description?: string; diff --git a/plugins/home-react/src/alpha.ts b/plugins/home-react/src/alpha.ts index 1a3432e02e..00b7a7bed7 100644 --- a/plugins/home-react/src/alpha.ts +++ b/plugins/home-react/src/alpha.ts @@ -25,9 +25,9 @@ */ export { homeReactTranslationRef } from './translation'; export { - HomepageWidgetBlueprint, - type HomepageWidgetBlueprintParams, -} from './alpha/blueprints/HomepageWidgetBlueprint'; + HomePageWidgetBlueprint, + type HomePageWidgetBlueprintParams, +} from './alpha/blueprints/HomePageWidgetBlueprint'; export { HomePageLayoutBlueprint, type HomePageLayoutBlueprintParams, diff --git a/plugins/home-react/src/alpha/blueprints/HomepageWidgetBlueprint.tsx b/plugins/home-react/src/alpha/blueprints/HomePageWidgetBlueprint.tsx similarity index 91% rename from plugins/home-react/src/alpha/blueprints/HomepageWidgetBlueprint.tsx rename to plugins/home-react/src/alpha/blueprints/HomePageWidgetBlueprint.tsx index e3375f2cb9..1dd1dc5501 100644 --- a/plugins/home-react/src/alpha/blueprints/HomepageWidgetBlueprint.tsx +++ b/plugins/home-react/src/alpha/blueprints/HomePageWidgetBlueprint.tsx @@ -28,8 +28,12 @@ import { } from '../../extensions'; import { homePageWidgetDataRef } from '../dataRefs'; -/** @alpha */ -export interface HomepageWidgetBlueprintParams { +/** + * Parameters for creating a home page widget extension. + * + * @alpha + */ +export interface HomePageWidgetBlueprintParams { /** * Optional name for the widget. If not provided, the extension will use only its kind * in the extension ID. @@ -71,14 +75,14 @@ const DEFAULT_WIDGET_ATTACH_POINT = { * * @alpha */ -export const HomepageWidgetBlueprint = createExtensionBlueprint({ - kind: 'home-widget', +export const HomePageWidgetBlueprint = createExtensionBlueprint({ + kind: 'home-page-widget', attachTo: DEFAULT_WIDGET_ATTACH_POINT, dataRefs: { widget: homePageWidgetDataRef, }, output: [homePageWidgetDataRef], - *factory(params: HomepageWidgetBlueprintParams, { node }) { + *factory(params: HomePageWidgetBlueprintParams, { node }) { const isCustomizable = params.settings?.schema !== undefined; const LazyCard = lazy(() => params.components().then(parts => ({ diff --git a/plugins/home/README.md b/plugins/home/README.md index fe16c3f221..e2da69a32b 100644 --- a/plugins/home/README.md +++ b/plugins/home/README.md @@ -114,17 +114,17 @@ app: Homepage widgets are React components that can be added to customizable home pages. The **key difference** between the new frontend system and legacy system is how these widget components are **registered and exported**: -- **New Frontend System**: Use `HomepageWidgetBlueprint` to register widgets as extensions +- **New Frontend System**: Use `HomePageWidgetBlueprint` to register widgets as extensions - **Legacy System**: Use `createCardExtension` to export widgets as card components ### New Frontend System -Create widgets using the `HomepageWidgetBlueprint`: +Create widgets using the `HomePageWidgetBlueprint`: ```ts -import { HomepageWidgetBlueprint } from '@backstage/plugin-home-react/alpha'; +import { HomePageWidgetBlueprint } from '@backstage/plugin-home-react/alpha'; -const myWidget = HomepageWidgetBlueprint.make({ +const myWidget = HomePageWidgetBlueprint.make({ name: 'my-widget', params: { name: 'MyWidget', diff --git a/plugins/home/dev/index.tsx b/plugins/home/dev/index.tsx index ce292c4ee5..954bf21740 100644 --- a/plugins/home/dev/index.tsx +++ b/plugins/home/dev/index.tsx @@ -28,7 +28,7 @@ import { createFrontendModule, } from '@backstage/frontend-plugin-api'; import { - HomepageWidgetBlueprint, + HomePageWidgetBlueprint, HomePageLayoutBlueprint, } from '@backstage/plugin-home-react/alpha'; import { HeaderWorldClock, WelcomeTitle, type ClockConfig } from '../src'; @@ -102,7 +102,7 @@ const homePageLayout = HomePageLayoutBlueprint.make({ }, }); -const homePageToolkitWidget = HomepageWidgetBlueprint.make({ +const homePageToolkitWidget = HomePageWidgetBlueprint.make({ name: 'home-toolkit', params: { name: 'HomePageToolkit', @@ -124,7 +124,7 @@ const homePageToolkitWidget = HomepageWidgetBlueprint.make({ }, }); -const homePageStarredEntitiesWidget = HomepageWidgetBlueprint.make({ +const homePageStarredEntitiesWidget = HomePageWidgetBlueprint.make({ name: 'home-starred-entities', params: { name: 'HomePageStarredEntities', @@ -136,7 +136,7 @@ const homePageStarredEntitiesWidget = HomepageWidgetBlueprint.make({ }, }); -const homePageRandomJokeWidget = HomepageWidgetBlueprint.make({ +const homePageRandomJokeWidget = HomePageWidgetBlueprint.make({ name: 'home-random-joke', params: { name: 'HomePageRandomJoke',