Backstage 홈페이지 - 설정 및 커스터마이징
홈 플러그인은 사용자가 URL을 외우지 않아도 필요한 것을 찾을 수 있는 홈페이지를 Backstage 앱에 제공해요. 드래그 앤 드롭 그리드 레이아웃과 내장 위젯 모음을 함께 제공하며, 사용자는 위젯을 추가·제거·재배열·크기 조정하고 그 레이아웃은 사용자별로 저장돼요. 이 글에서는 홈 플러그인 설치부터 맞춤 위젯 생성까지 전체 과정을 안내할게요.
출처: 문서
본문
이 문서는 새 Backstage 앱에서 기본값으로 사용되는 새 프론트엔드 시스템을 기준으로 작성되었어요. 만약 Backstage 앱이 아직 이전 프론트엔드 시스템을 사용하고 있다면, 이 가이드의 이전 프론트엔드 시스템 버전을 읽어보세요.
홈페이지
홈 플러그인은 사용자가 URL을 외우지 않아도 필요한 것을 찾을 수 있는 홈페이지를 Backstage 앱에 제공해요. 이 플러그인은 드래그 앤 드롭 그리드 레이아웃과 내장 위젯 모음을 함께 제공해요. 사용자는 위젯을 추가·제거·재배열·크기 조정할 수 있고, 그 레이아웃은 사용자별로 저장돼요.
이 가이드에서 다루는 내용은 다음과 같아요:
-
홈 플러그인을 설치하고 랜딩 페이지로 만드는 방법.
-
어떤 위젯을 사용할 수 있고 어떻게 구성하는지.
-
직접 위젯과 레이아웃을 만드는 방법.
사전 준비 사항
시작하기 전에 다음을 확인하세요:
-
@backstage/create-app을 사용해 직접 독립 실행형 Backstage 앱을 만들었고, backstage 저장소의 포크를 사용하지 않았어요. -
기존 홈페이지가 없고, 기본적으로 Backstage를 열면 소프트웨어 카탈로그로 리디렉션돼요.
설정
1. 플러그인 설치하기
Backstage 루트 디렉터리에서
yarn --cwd packages/app add @backstage/plugin-home
설치가 완료되면 기본 기능 탐색을 통해 플러그인을 앱에서 사용할 수 있어요. 다른 설치 방법은 플러그인 설치를 참고하세요.
2. 홈페이지를 루트 라우트로 구성하기
홈페이지는 기본적으로 /home에 위치해요. 이를 /의 랜딩 페이지로 만들려면 app-config.yaml에 다음을 추가해요:
app-config.yaml
app: extensions: - page:home: config: path: /
플러그인은 사이드바에 "Home" 탐색 항목을 자동으로 추가해요.
3. 방문 추적 활성화하기 (선택 사항)
방문 추적은 사용자가 방문한 페이지를 기록해요. Most Visited와 Recently Visited 위젯이 이 데이터를 사용해요. 기본적으로 비활성화되어 있어요.
활성화하면 방문 데이터는 다음 두 곳 중 한 곳에 저장돼요:
-
지속적 저장소가 있는 UserSettings 플러그인을 사용한다면 UserSettings 저장소(권장). 데이터가 기기 간에 동기화돼요.
-
지속적 저장소가 없으면 브라우저 로컬 저장소를 대안으로 사용해요.
활성화하려면 app-config.yaml에 다음 확장을 추가해요:
app-config.yaml
app: extensions: - api:home/visits: true - app-root-element:home/visit-listener: true
사용 가능한 위젯
다음 위젯은 기본으로 제공되며, 홈페이지를 편집할 때 Add Widget 대화상자에 나타나요.
홈 플러그인 위젯
이 위젯들은 @backstage/plugin-home에서 제공돼요:
| | 위젯 | 확장 ID | 설명 | Starred Entities | home-page-widget:home/starred-entities | 카탈로그에서 즐겨찾기한 엔티티를 보여줘요. | Toolkit | home-page-widget:home/toolkit | 구성 가능한 링크와 도구의 모음이에요. | World Clocks | home-page-widget:home/world-clock | 구성된 시간대의 시계를 표시해요. | Most Visited | home-page-widget:home/most-visited | 가장 자주 방문한 페이지를 보여줘요. 방문 추적이 필요해요. | Recently Visited | home-page-widget:home/recently-visited | 최근에 방문한 페이지를 보여줘요. 방문 추적이 필요해요. | Random Joke | home-page-widget:home/random-joke | 무작위 프로그래밍 농담을 보여줘요.
검색 플러그인 위젯
이 위젯은 @backstage/plugin-search에서 제공돼요:
| | 위젯 | 확장 ID | 설명 | Search Bar | home-page-widget:search/search-bar | 제출 시 검색 페이지로 이동하는 검색 바예요.
검색 바 위젯을 사용하려면 @backstage/plugin-search가 설치되어 있어야 해요.
커뮤니티 위젯
Backstage 커뮤니티 플러그인 저장소에는 추가 플러그인이 호스팅되어 있고, 그중 일부는 홈페이지 위젯을 제공해요. 모든 플러그인은 @backstage/plugin-home-react/alpha의 HomePageWidgetBlueprint를 사용해서 홈페이지에 위젯을 기여할 수 있어요.
위젯 구성하기
일부 위젯은 app-config.yaml을 통해 구성을 받아들여요. 확장 ID로 위젯을 지정해요.
Toolkit
Toolkit 위젯은 링크 그리드를 보여줘요. 링크와 아이콘을 구성할 수 있어요:
app-config.yaml
app: extensions: - home-page-widget:home/toolkit: config: tools: - url: https://backstage.io/docs label: Docs icon: docs - url: https://github.com/backstage/backstage label: GitHub icon: github - url: https://backstage.io/plugins label: Plugins Directory icon: kind:component
icon 필드는 앱의 아이콘 API를 통해 해석돼요. kind: 접두사를 붙인 카탈로그 엔티티 종류용 아이콘을 포함해 등록된 어떤 아이콘이든 사용할 수 있어요.
World Clocks
표시할 시간대와 시간 형식을 구성해요:
app-config.yaml
app: extensions: - home-page-widget:home/world-clock: config: customTimeFormat: hour12: false clockConfigs: - label: NYC timeZone: America/New_York - label: UTC timeZone: UTC - label: STO timeZone: Europe/Stockholm - label: TYO timeZone: Asia/Tokyo
위젯 비활성화하기
Add Widget 대화상자에서 위젯을 숨기려면 false로 설정해요:
app-config.yaml
app: extensions: - home-page-widget:home/random-joke: false
기본 레이아웃 구성하기
page:home의 defaultConfig 옵션은 사용자가 아무것도 커스터마이징하기 전에 보게 되는 그리드 레이아웃을 정의해요. 각 항목은 위젯을 그리드의 특정 위치와 크기에 배치해요:
app-config.yaml
app: extensions: - page:home: config: path: / defaultConfig: - component: HomePageSearchBar column: 0 row: 0 width: 12 height: 2 deletable: false - component: HomePageStarredEntities column: 0 row: 2 width: 4 height: 4 - component: HomePageToolkit column: 4 row: 2 width: 4 height: 3 - component: HomePageWorldClock column: 8 row: 2 width: 4 height: 3
defaultConfig의 각 항목은 다음 속성을 받아들여요:
| | 속성 | 유형 | 설명 | component | string | 위젯의 컴포넌트 이름(블루프린트의 name 매개변수). | column | number | 그리드의 열 위치(0부터 시작). | row | number | 그리드의 행 위치(0부터 시작). | width | number | 그리드 열로 표현한 너비. 기본 그리드는 12열로 구성돼요. | height | number | 그리드 행으로 표현한 높이. | movable | boolean | 사용자가 위젯을 이동할 수 있는지. 기본값은 true. | deletable | boolean | 사용자가 위젯을 제거할 수 있는지. 기본값은 true. | resizable | boolean | 사용자가 위젯 크기를 조정할 수 있는지. 기본값은 true.
편집 모드에서 각 위젯은 column, row, width, height 값을 표시해요. 이 값을 사용해서 defaultConfig에 맞는 숫자를 파악할 수 있어요.
맞춤 위젯 만들기
@backstage/plugin-home-react/alpha의 HomePageWidgetBlueprint를 사용해서 직접 위젯을 추가할 수 있어요. 위젯을 정의하고, 프론트엔드 모듈로 감싼 다음 앱에 등록해요.
기본 위젯
packages/app/src/modules/home/homeModule.tsx
import { createFrontendModule } from '@backstage/frontend-plugin-api';import { HomePageWidgetBlueprint } from '@backstage/plugin-home-react/alpha';const myWidget = HomePageWidgetBlueprint.make({ name: 'my-widget', params: { name: 'MyWidget', title: 'My Custom Widget', description: 'A short description shown in the Add Widget dialog', components: () => import('./MyWidgetComponent').then(m => ({ Content: m.Content, })), },});export const homeModule = createFrontendModule({ pluginId: 'home', extensions: [myWidget],});
그런 다음 앱에 모듈을 등록해요:
packages/app/src/App.tsx
import { homeModule } from './modules/home';export default createApp({ features: [homeModule],});
레이아웃 제약이 있는 위젯
위젯이 너무 작아지거나 커지지 않도록 최소·최대 크기를 설정해요:
const myWidget = HomePageWidgetBlueprint.make({ name: 'my-widget', params: { name: 'MyWidget', title: 'My Custom Widget', description: 'A widget with size constraints', components: () => import('./MyWidgetComponent').then(m => ({ Content: m.Content, })), layout: { height: { minRows: 4 }, width: { minColumns: 3 }, }, },});
사용자 설정이 있는 위젯
위젯은 사용자별 설정을 노출할 수 있어요. 설정 스키마는 react-jsonschema-form 규칙을 따르고 있어요:
const myWidget = HomePageWidgetBlueprint.make({ name: 'my-widget', params: { name: 'MyWidget', title: 'My Custom Widget', description: 'A widget with user-configurable settings', components: () => import('./MyWidgetComponent').then(m => ({ Content: m.Content, Settings: m.Settings, })), settings: { schema: { title: 'Widget Settings', type: 'object', properties: { color: { title: 'Color', type: 'string', default: 'blue', enum: ['blue', 'red', 'green'], }, }, }, }, },});
맞춤 홈페이지 레이아웃
기본 그리드가 요구에 맞지 않으면 전체를 교체할 수 있어요. @backstage/plugin-home-react/alpha의 HomePageLayoutBlueprint를 사용해서 설치된 위젯을 받아 원하는 방식으로 렌더링하는 레이아웃 컴포넌트를 만들 수 있어요.
packages/app/src/modules/home/homeModule.tsx
import { createFrontendModule } from '@backstage/frontend-plugin-api';import { HomePageLayoutBlueprint, type HomePageLayoutProps,} 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 myLayout = HomePageLayoutBlueprint.make({ params: { loader: async () => function MyHomePageLayout({ widgets }: HomePageLayoutProps) { return ( <Page themeId="home"> <Header title="Welcome" /> <Content> <CustomHomepageGrid> {widgets.map((widget, index) => ( <Fragment key={widget.name ?? index}> {widget.component} </Fragment> ))} </CustomHomepageGrid> </Content> </Page> ); }, },});export const homeModule = createFrontendModule({ pluginId: 'home', extensions: [myLayout],});
맞춤 레이아웃이 설치되어 있지 않으면 플러그인은 위젯을 CustomHomepageGrid 안에 렌더링하는 기본 제공 레이아웃으로 대체돼요.
중복 위젯 방지하기
기본적으로 사용자는 같은 위젯의 인스턴스를 여러 개 추가할 수 있어요. CustomHomepageGrid와 함께 맞춤 레이아웃을 사용한다면 preventDuplicateWidgets prop을 전달해서 각 위젯을 단일 인스턴스로 제한할 수 있어요. 이 옵션은 맞춤 레이아웃이 필요해요. app-config 설정으로 노출되지는 않아요.
<CustomHomepageGrid preventDuplicateWidgets> {widgets.map((widget, index) => ( <Fragment key={widget.name ?? index}>{widget.component}</Fragment> ))}</CustomHomepageGrid>