선언적 통합 검색 플러그인
선언적 통합(declarative integration) 방식으로 Search를 실험하기 위한 가이드예요.
출처: 문서
본문
고지(Disclaimer): 선언적 통합은 실험 단계이며 프로덕션에는 권장되지 않아요.
이 가이드는 선언적 통합 방식의 Backstage 프론트엔드 애플리케이션에서 Search를 실험하기 위한 문서예요.
주요 개념 (Main Concepts)
선언적 통합을 사용하면 코드를 작성하지 않고도 Backstage 인스턴스를 사용자 지정할 수 있어요. 자세한 내용은 이 RFC 문서를 참고하세요.
새 프론트엔드 시스템에서 Backstage의 핵심 기능을 확장하는 모든 것은 확장(extension)이라고 불러요. 따라서 확장은 API에서 페이지 컴포넌트까지 무엇이든 될 수 있어요.
확장은 출력 산출물(output artifact)을 생성하며, 이 산출물은 다른 확장이 소비하는 입력이 돼요.
위 이미지에서 SearchResultItem 확장이 컴포넌트를 출력하고, 이 컴포넌트는 SearchPage의 "items" 부착 지점(attachment point)에 입력으로 주입돼요. SearchPage는 다시 검색 결과 항목들을 사용해 검색 페이지 요소를 구성하고, 경로(route path)와 페이지 요소를 출력해 CoreRoutes 확장에 입력으로 부착해요. 마지막으로 CoreRoutes는 위치(location)가 검색 페이지 경로와 일치할 때 페이지 요소를 렌더링해요.
간단히 언급한 기본 개념들은 Search 플러그인의 선언적 버전이 어떻게 동작하는지 이해하는 데 중요해요.
Search 플러그인
검색 플러그인은 Backstage에서 검색 기능을 구현하는 확장들의 모음이에요.
설치 (Installation)
선언적 통합에서 Search 플러그인을 사용하기 시작하는 데는 단 한 단계만 필요해요. @backstage/plugin-catalog와 @backstage/plugin-search 패키지(예: app)를 설치하기만 하면 돼요.
yarn add @backstage/plugin-catalog @backstage/plugin-search
Search 플러그인은 Catalog API에 의존하므로 @backstage/plugin-catalog 패키지도 함께 설치해야 해요.
확장 (Extensions)
Search 플러그인은 다음과 같은 확장 사전 설정(preset)을 제공해요.
-
SearchApi:
Search API의 구체적인 구현을 출력하며,CoreAPI 보유자(api holder)에 입력으로 부착돼요. -
SearchPage: 고급
Search페이지 인터페이스를 나타내는 컴포넌트를 출력해요. 이 확장은 사용자 지정 방식으로 결과를 렌더링하기 위해Search결과 항목 컴포넌트들을 입력으로 기대해요. -
SearchNavItem: 메인 애플리케이션 사이드바에서
Search항목을 나타내는 데이터를 출력하는 확장이에요. 즉Core네비게이션 확장에 사이드바 항목을 입력하는 것이에요.
구성 (Configurations)
Search 확장은 app-config.yaml 파일의 app.extensions 필드에서 확장 id를 구성 키로 사용해 설정할 수 있어요.
검색 페이지 확장을 비활성화하는 예시
# app-config.yamlapp: extensions: - page:search: false # ✨
검색 페이지 제목(사이드바에 사용)을 설정하는 예시
# app-config.yamlapp: extensions: - page:search: # ✨ config: title: 'Search Page'
알려진 제한 사항: 현재 사이드바 항목에서 모달을 열거나 구성 파일로 다른 아이콘을 설정하는 것은 불가능하지만, 이미 관리자(manager/maintainer)가 인지하고 있어요.
사용자 지정 (Customizations)
플러그인 개발자는 @backstage/plugin-search-react/alpha의 SearchResultListItemBlueprint를 사용해 나만의 사용자 지정 검색 결과 항목 확장을 만들 수 있어요.
사용자 지정 TechDocsSearchResultItemExtension을 만드는 예시
// plugins/techdocs/src/alpha.tsximport { SearchResultListItemBlueprint } from '@backstage/plugin-search-react/alpha';export const TechDocsSearchResultListItemExtension = SearchResultListItemBlueprint.make({ name: 'techdocs', params: { predicate: result => result.type === 'techdocs', component: async ({ config }) => { const { TechDocsSearchResultListItem } = await import( './components/TechDocsSearchResultListItem' ); return props => <TechDocsSearchResultListItem {...props} {...config} />; }, }, });
위 코드 조각에서 플러그인 개발자는 "techdocs" 유형의 검색 결과를 렌더링하기 위한 사용자 지정 컴포넌트를 제공하고 있어요. 이 사용자 지정 결과 항목 확장은 @backstage/plugin-techdocs 패키지가 설치되면 기본으로 활성화되며, 즉 도입자(adopter)가 구성 파일을 통해 확장을 수동으로 활성화할 필요가 없어요.
TechDocs 플러그인을 설치한 후 사용자 지정 TechDocs 검색 결과 항목을 사용하지 않으려면 Backstage 구성 파일로 비활성화할 수 있어요.
# app-config.yamlapp: extensions: - search-result-list-item:techdocs: false
SearchResultListItemBlueprint에는 자동 분석(analytics) 이벤트 추적을 비활성화하는 데 사용할 수 있는 내장 noTrack 구성 옵션이 포함돼 있어요.
# app-config.yamlapp: extensions: - search-result-list-item:techdocs: config: noTrack: true
사용자 지정 검색 결과 항목 확장의 개발 사이클을 완성하려면 TechDocs 플러그인을 통해 확장을 제공하세요. 실제 사용자 지정 TechDocs 검색 결과 항목 구현도 살펴볼 수 있어요.
// plugins/techdocs/src/alpha.tsximport { createFrontendPlugin } from '@backstage/frontend-plugin-api';import { SearchResultListItemBlueprint } from '@backstage/plugin-search-react/alpha';const TechDocsSearchResultListItemExtension = SearchResultListItemBlueprint.make({ name: 'techdocs', params: { predicate: result => result.type === 'techdocs', component: async ({ config }) => { const { TechDocsSearchResultListItem } = await import( './components/TechDocsSearchResultListItem' ); return props => <TechDocsSearchResultListItem {...props} {...config} />; }, }, });export default createFrontendPlugin({ id: 'techdocs', extensions: [TechDocsSearchResultListItemExtension],});
향후 개선 기회 (Future Enhancement Opportunities)
Backstage 관리자들은 확장 교체(replacement) 기능을 작업 중이며, 이 릴리스에서는 도입자들이 플러그인이 제공하는 확장도 교체할 수 있게 될 거예요. 향후 이 문서의 업데이트를 기대해 주세요.
SearchPage 확장의 첫 버전은 Search 플러그인 관리자들이 향후 필터도 확장으로 전환할 수 있는 여지를 만들어 줘요. 이 아이디어에 함께 협력하고 싶다면 주저하지 말고 이슈를 열고 풀 리퀘스트를 제출해 주세요. 여러분의 기여는 언제나 환영이에요!