Backstage Home Screen Transformation! Essential Guide to Rendering Custom Widgets 🛠️

Hello, platform engineers! 👋 One of the first things you’ll want to do after adopting Backstage is to create a “custom home screen just for your team.”

You’ve written some great custom widget code, but why isn’t it appearing on the home screen? Beyond simply creating a component, you need a ‘connecting link’ that allows the Backstage home plugin to recognize it. From now on, I’ll explain the core secret in detail!

---

1. Basic Principles of Home Page Widgets 🧩

Backstage’s Home page is not just a single page, but a dynamic layout composed of multiple Widgets. For your custom widget to appear on the home screen, two main things need to be prepared:

1. Widget Component: The React code that will actually be rendered on the screen.
2. Widget Extension: The process of wrapping this component so that Backstage can recognize it as a ‘home widget’.

---

2. Step 1: Create a Widget Component 💻

First, you need to write the actual content to be displayed on the home screen. This is usually located in the src/components folder of your plugin.

TypeScript

// MyCustomWidget.tsx
import React from 'react';
import { InfoCard } from '@backstage/core-components';

export const MyCustomWidget = () => (
  <InfoCard title="오늘의 공지사항 📢">
    <p>플랫폼 팀에서 전합니다. 오늘은 정기 점검일입니다!</p>
  </InfoCard>
);

---

3. Step 2: The Core! Define the Widget Extension 🔗

This step is the direct answer to the question. Instead of just exporting the widget, you must register it using the createCardExtension function.

• Reason: The Backstage home plugin reads the widget’s metadata through this extension and safely places the widget in the layout engine.

TypeScript

// plugin.ts
import { createCardExtension } from '@backstage/plugin-home';
import { rootRouteRef } from './routes';

export const MyCustomWidgetExtension = homePlugin.provide(
  createCardExtension({
    name: 'MyCustomWidget',
    title: '나의 커스텀 위젯',
    components: () => import('./components/MyCustomWidget').then(m => m.MyCustomWidget),
    // You can set the path to navigate to when the widget is clicked, etc.
  }),
);

---

4. Step 3: Place the Widget on HomePage.tsx 🏠

Once you’ve defined the Extension, you now need to go to the actual home page configuration file (App.tsx or HomePage.tsx) and add this widget to the rendering tree.

TypeScript

// App.tsx or HomePage.tsx
import { MyCustomWidgetExtension } from '@internal/plugin-my-custom-plugin';

// ... (omitted)
<Grid item xs={12} md={6}>
  <MyCustomWidgetExtension />
</Grid>

Important Note! If the widget depends on other plugins or requires Permissions, that context must exist higher up in the hierarchy.

---

5. Checklist for Successful Rendering ✅

If your widget isn’t appearing on the screen, be sure to check these 3 things!

1. Export Status: Have you correctly exported the widget extension (MyCustomWidgetExtension) from your plugin’s index.ts?
2. Layout Settings: Is the widget occupying too small an area within layout components like tags? (Check xs, md values)
3. Dynamic Import (Lazy Loading): If you used the components: () => import(…) format, ensure the path is accurate.

---

6. Summary: What should you do? 📝

To render a custom widget on the Backstage home page, you must do the following:

• You must wrap and export the widget with createCardExtension.
• Then, you must place that extension component within your app’s home page layout (HomePage.tsx).

---

🏁 Concluding Remarks

The Backstage home page is the ‘starting point’ for developers. Create custom widgets for information your team members need to check most frequently (e.g., on-call rotation, build status, team announcements). Even a small widget can significantly boost your team’s productivity! 🚀

---