Backstage 홈 화면의 변신! 커스텀 위젯을 렌더링하는 필수 가이드 🛠️

안녕하세요, 플랫폼 엔지니어 여러분! 👋 Backstage를 도입하고 가장 먼저 하고 싶은 일 중 하나가 바로 "우리 팀만을 위한 맞춤형 홈 화면"을 만드는 것일 텐데요.

멋진 커스텀 위젯 코드를 짰는데, 왜 홈 화면에 나타나지 않을까요? 단순히 컴포넌트를 만드는 것에서 나아가, Backstage 홈 플러그인이 이를 인식하게 만드는 '연결 고리'가 필요합니다. 지금부터 그 핵심 비법을 상세히 알려드릴게요!

---

1. 홈 페이지 위젯의 기본 원리 🧩

Backstage의 홈 페이지(Home page)는 단순히 하나의 페이지가 아니라, 여러 위젯(Widgets)들이 모여 구성되는 동적인 레이아웃입니다. 여러분이 만든 커스텀 위젯이 홈 화면에 나타나려면 크게 두 가지가 준비되어야 합니다.

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. Export 여부: 플러그인의 index.ts에서 위젯 확장(MyCustomWidgetExtension)을 올바르게 export 했나요?
2. 레이아웃 설정: 태그 등 레이아웃 컴포넌트 안에서 위젯이 너무 작은 영역을 차지하고 있지는 않나요? (xs, md 값 확인)
3. 동적 임포트(Lazy Loading): components: () => import(...) 형식을 사용했다면 경로가 정확한지 확인하세요.

---

6. 요약: 무엇을 해야 하나요? 📝

Backstage 홈 페이지에 커스텀 위젯을 렌더링하기 위해 반드시 해야 할 일은 다음과 같습니다.

• 위젯을 createCardExtension으로 감싸서(Wrap) 내보내야 합니다.
• 그 후, 앱의 홈 페이지 레이아웃(HomePage.tsx) 내에 해당 확장 컴포넌트를 배치해야 합니다.

---

🏁 마무리하며

Backstage 홈 페이지는 개발자들의 '시작점'입니다. 팀원들이 가장 자주 확인해야 하는 정보(예: 온콜 순번, 빌드 상태, 팀 공지)를 커스텀 위젯으로 만들어 보세요. 작은 위젯 하나가 팀 전체의 생산성을 크게 높여줄 수 있습니다! 🚀

---