Backstageホーム画面の変革！カスタムウィジェットをレンダリングするための必須ガイド 🛠️

プラットフォームエンジニアの皆さん、こんにちは！ 👋 Backstageを導入してまずやりたいことの一つが、「私たちのチーム専用のカスタムホーム画面」を作ることではないでしょうか。

素晴らしいカスタムウィジェットのコードを書いたのに、なぜホーム画面に表示されないのでしょうか？単にコンポーネントを作成するだけでなく、Backstageホームプラグインがそれを認識できるようにする「接続の鍵」が必要です。これからその核心的な秘訣を詳しくお伝えします！

---

1. ホームページウィジェットの基本原理 🧩

Backstageのホーム画面（Home page）は、単一のページではなく、複数のウィジェット（Widgets）が集まって構成される動的なレイアウトです。作成したカスタムウィジェットがホーム画面に表示されるためには、大きく分けて2つの準備が必要です。

1. ウィジェットコンポーネント（Widget Component）： 実際に画面に描画されるReactコード。
2. ウィジェット拡張（Widget Extension）： Backstageがこのコンポーネントを「ホームウィジェット」として認識できるようにラッピングするプロセス。

---

2. ステップ1：ウィジェットコンポーネントの作成 💻

まず、ホーム画面に表示する実際のコンテンツを作成する必要があります。これは通常、プラグインのsrc/componentsフォルダ内に配置されます。

TypeScript

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

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

---

3. ステップ2：核心！ウィジェット拡張（Extension）の定義 🔗

このステップがまさに質問への直接的な回答です。ウィジェットを単にエクスポートするのではなく、createCardExtension関数を使用して登録する必要があります。

• 理由： Backstageホームプラグインは、この拡張を通じてウィジェットのメタデータを読み取り、レイアウトエンジンにウィジェットを安全に配置します。

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),
    // ウィジェットがクリックされたときに移動するパスなどを設定できます。
  }),
);

---

4. ステップ3：HomePage.tsxにウィジェットを配置 🏠

拡張（Extension）まで定義したら、次に実際のホーム画面構成ファイル（App.tsxまたはHomePage.tsx）に移動し、このウィジェットをレンダリングツリーに追加する必要があります。

TypeScript

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

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

ここで注意点！ ウィジェットが他のプラグインに依存したり、権限（Permissions）が必要な場合は、そのコンテキストが上位に存在する必要があります。

---

5. 成功的なレンダリングのためのチェックリスト ✅

ウィジェットが画面に表示されない場合は、次の3つのことを必ず確認してください！

1. エクスポートの有無： プラグインのindex.tsからウィジェット拡張（MyCustomWidgetExtension）を正しくエクスポートしましたか？
2. レイアウト設定： タグなどのレイアウトコンポーネント内でウィジェットが小さすぎる領域を占めていませんか？（xs、mdの値を確認）
3. 動的インポート（Lazy Loading）： `components: () => import(…)`形式を使用した場合、パスが正確か確認してください。

---

6. 要約：何をすべきか？ 📝

Backstageホーム画面にカスタムウィジェットをレンダリングするために、必ず行うべきことは次のとおりです。

• ウィジェットをcreateCardExtensionでラップして（Wrap）エクスポートする必要があります。
• その後、アプリのホーム画面レイアウト（HomePage.tsx）内にその拡張コンポーネントを配置する必要があります。

---

🏁 終わりに

Backstageホーム画面は開発者の「出発点」です。チームメンバーが最も頻繁に確認する必要がある情報（例：オンコール当番、ビルドステータス、チームのお知らせ）をカスタムウィジェットとして作成してみてください。小さなウィジェット一つがチーム全体の生産性を大幅に向上させることができます！ 🚀

---