앱 내장 확장

앱 내장 확장 (App Built-in Extensions)

내장 확장은 Backstage 앱을 만들 때 항상 설치되는 기본 앱 확장이에요.

출처: 문서

본문

내장 확장은 Backstage 앱을 만들 때 항상 설치되는 기본 앱 확장이에요.

내장 확장 비활성화하기

모든 내장 확장은 다른 확장을 비활성화하는 것과 같은 방식으로 비활성화할 수 있어요.

app-config.yaml

extensions:  # Disabling the built-in app root alert element  - app-root-element:app/alert-display: false

경고

내장 확장을 비활성화할 때는 다른 확장이 그 존재에 의존할 수 있으므로 주의해야 해요. 예를 들어 내장 "alert display"(알림 표시) 확장은 AlertApi를 통해 검색된 메시지를 표시하며, 이 확장을 비활성화하면 AlertApi에서 메시지를 표시하는 다른 확장을 설치하지 않는 한 애플리케이션이 더 이상 이러한 메시지를 표시하지 않게 돼요.

내장 확장 재정의하기

구성이나 입력을 통한 커스터마이즈가 Backstage 인스턴스의 사용 사례를 충족하지 못할 때 내장 확장을 재정의할 수 있어요. 앱 확장을 재정의하는 방법에 대한 이 문서를 확인하세요.

경고

내장 확장을 올바르게 재정의하려면 같은 API를 사용하고 입력이나 구성을 제거하지 않는 등 몇 가지 구현 요구 사항이 있을 수 있어요. 그렇지 않으면 같은 최소 동작을 기대하는 시스템의 다른 부분에 부작용을 일으킬 수 있어요.

기본 내장 확장

App

이 확장은 확장 트리에 부착된 첫 번째 확장이에요. 애플리케이션의 루트 요소와 다른 프론트엔드 프레임워크 입력을 받는 책임을 져요.

입력

이름	설명	유형	선택	기본값	확장 생성자
root	앱 루트 요소.	coreExtensionData.reactElement	false	App/Root 확장 출력.	생성자 없음, App/Root 확장을 구성하거나 재정의.
apis	앱 API 팩토리.	createApiExtension.factoryDataRef	false	기본 apis 참고.	createApiExtension
themes	앱 테마 목록.	createThemeExtension.themeDataRef	false	기본 themes 참고.	createThemeExtension
components	앱 컴포넌트 목록.	SwappableComponentBlueprint.dataRefs.component	false	기본 components 참고.	SwappableComponentBlueprint
translations	앱 번역 목록.	createTranslationExtension.translationDataRef	false	-	createTranslationExtension
icons	앱 아이콘 목록.	IconBundleBlueprint.dataRefs.icons	true	-	IconBundleBlueprint

기본 테마 확장

App 확장에 기본 테마 입력을 제공하는 확장이에요.

kind	namespace	name	id
theme	app	light	theme:app/light
theme	app	dark	theme:app/dark

기본 컴포넌트 확장

App 확장에 기본 컴포넌트 입력을 제공하는 확장이에요.

kind	namespace	name	id
components	app	core-progress	components:app/core-progress
components	app	core-not-found-error-page	components:app/core-not-found-error-page
components	app	core-error-display	components:app/core-error-display

기본 apis 확장

App 확장에 기본 apis 입력을 제공하는 확장이에요.

kind	namespace	name	id
api	core.discovery	-	api:core.discovery
api	core.alert	-	api:core.alert
api	core.analytics	-	api:core.analytics
api	core.error	-	api:core.error
api	core.storage	-	api:core.storage
api	core.fetch	-	api:core.fetch
api	core.oauthrequest	-	api:core.oauthrequest
api	core.auth.google	-	api:core.auth.google
api	core.auth.microsoft	-	api:core.auth.microsoft
api	core.auth.github	-	api:core.auth.github
api	core.auth.okta	-	api:core.auth.okta
api	core.auth.gitlab	-	api:core.auth.gitlab
api	core.auth.onelogin	-	api:core.auth.onelogin
api	core.auth.bitbucket	-	api:core.auth.bitbucket
api	core.auth.bitbucket-server	-	api:core.auth.bitbucket-server
api	core.auth.atlassian	-	api:core.auth.atlassian
api	plugin.permission.api	-	api:plugin.permission.api

App root

앱 루트 요소를 만드는 확장으로, 앱 라우터와 레이아웃 같은 루트 수준 컴포넌트를 렌더링해요.

입력

이름	설명	요구 사항	선택	기본값	확장 생성자
router	앱 라우트 컨텍스트를 관리해야 하는 React 컴포넌트.	라우터 컴포넌트 하나 또는 'react-router' 라이브러리와 호환되는 커스텀 컴포넌트여야 함.	true	BrowserRouter	createRouterExtension
signInPage	앱 로그인 페이지를 렌더링해야 하는 React 컴포넌트.	사용자가 성공적으로 인증되면 onSignInSuccess prop을 호출해야 하며, 그렇지 않으면 사용자가 애플리케이션 홈 페이지로 올바르게 리다이렉트되지 않음.	true	기본 AppRoot 확장은 이 입력에 기본 컴포넌트를 사용하지 않고, 로그인 페이지가 설치되지 않으면 사용자 인증 검사를 건너뛰고 항상 모든 라우트를 렌더링함.	createSignInPageExtension
children	특정 레이아웃으로 앱 사이드바와 메인 콘텐츠를 렌더링하는 React 컴포넌트.	-	true	App/Layout 확장 출력.	생성자 없음, App/Layout 확장을 구성하거나 재정의.
elements	앱 레이아웃 밖에서 렌더링될 React 요소. 예: 공유 팝업.	-	false	기본 elements 참고.	AppRootElementBlueprint
wrappers	루트 요소를 감싸야 하는 React 컴포넌트.	-	true	-	createAppRootWrapperExtension

기본 앱 루트 요소 확장

Alert Display (알림 표시)

AlertApi를 통해 게시된 메시지를 표시하는 앱 루트 요소 확장이에요.

kind	namespace	name	id
app-root-element	app	alert-display	app-root-element:app/alert-display

구성

키	유형	기본값	설명
transientTimeoutMs	number	5000	메시지를 표시하기 전에 기다릴 시간(밀리초).
anchorOrigin	{ vertical: 'top' | 'bottom', horizontal: 'left' | 'center' | 'right' }	{ vertical: 'top', horizontal: 'center' }	메시지 알림이 표시될 화면 위치.

확장 재정의 또는 비활성화

알림을 표시하고 싶지 않으면 이 확장을 비활성화하거나, 사용 가능한 설정이 요구 사항을 충족하지 못하면 이 확장을 재정의하세요.

경고

내장 "alert display" 확장은 AlertApi를 통해 검색된 메시지를 표시하며, 이 확장을 비활성화하면 AlertApi에서 메시지를 표시하는 다른 확장을 설치하지 않는 한 애플리케이션이 더 이상 이러한 메시지를 표시하지 않게 돼요.

OAuth 요청 대화상자 (OAuth Request Dialog)

oauthRequestApi를 기반으로 oauth 요청 대화상자를 렌더링하는 앱 루트 요소 확장이에요.

kind	namespace	name	id
app-root-element	app	oauth-request-dialog	app-root-element:app/oauth-request-dialog

App layout

특정 레이아웃으로 앱의 사이드바와 콘텐츠를 렌더링해요.

kind	namespace	name	id
-	app	layout	app/layout

입력

이름	설명	유형	선택	기본값	확장 생성자
nav	앱 사이드바를 렌더링하는 React 요소.	coreExtensionData.reactElement	false	-	App/Nav 확장을 재정의.
content	앱 콘텐츠를 렌더링하는 React 요소.	coreExtensionData.reactElement	false	-	App/Routes 확장을 재정의.

App nav

앱 사이드바에서 로고와 항목을 렌더링하는 책임을 가진 확장이에요.

kind	namespace	name	id
-	app	nav	app/nav

입력

이름	설명	유형	선택	기본값	확장 생성자
content	내비게이션 바의 기본 콘텐츠를 재정의.	NavContentBlueprint.dataRefs.component	true	-	NavContentBlueprint

App routes

입력으로 받은 각 라우트에 대해 라우트 요소를 렌더링하고 NotFoundErrorPage 컴포넌트를 렌더링해요.

kind	namespace	name	id
-	app	routes	app/routes

주의 사항 (Caveats)

이 확장을 재정의할 때는 주의해야 해요. 올바르게 재정의하려면 다음 구현 요구 사항을 고려해야 하기 때문이에요.

• 라우팅 시스템은 하나 이상의 확장이 관리하며, 모두 내부에서 react-router를 사용해요. useRouteRefParams처럼 같은 routing 라이브러리를 기반으로 하는 유틸리티도 있어요. 따라서 다른 라이브러리를 사용하면 이 다른 확장과 헬퍼 유틸리티에 부작용을 일으킬 수 있어요.

• 구성을 제거하거나 입력을 제거하지 말고, 선택적인 새 옵션으로 직접 확장하세요. 그렇지 않으면 createPageExtension처럼 이 유형의 입력에 의존하는 확장에 큰 변경(breaking change)을 일으킬 거예요. (원문 그대로의 전문을 유지하기 위해 일부 표현을 보존했어요.)

• 경로를 동적으로 얻으려면 라우트 참조를 사용하는 것을 기억하세요. 그렇지 않으면 도입자가 구성을 통해 경로를 수정해도 라우트가 구성된 경로를 가리키지 않을 거예요.

• 도입자들은 Components API를 통해 NotFoundErrorPage 컴포넌트를 커스터마이즈할 수 있기를 기대해요. 구성되지 않은 라우트에는 이 컴포넌트를 렌더링해야 해요.

구성

키	유형	기본값	설명
redirects	{ from: string, to: string }[]	-	URL 리다이렉트 목록. from으로의 탐색은 to로 리다이렉트됨.

리다이렉트 구성하기

app/routes 확장용 리다이렉트를 구성해 사용자를 한 경로에서 다른 경로로 자동 리다이렉트할 수 있어요. 플러그인 페이지를 이동하거나 이름을 바꾼 뒤처럼 앱의 라우트를 재구성할 때 유용해요.

app-config.yaml

app:  extensions:    - app/routes:        config:          redirects:            - from: /old-path              to: /new-path            - from: /legacy/page              to: /updated/page

리다이렉트는 일반 라우트보다 먼저 일치하며 replace 전략을 사용하므로 이전 경로가 브라우저 히스토리에 나타나지 않아요.

입력

이름	설명	유형	선택	기본값	확장 생성자
routes	라우트 객체 목록.	{ path: coreExtensionData.routePath, ref: coreExtensionData.routeRef.optional(), element: coreExtensionData.reactElement }	false	-	createPageExtension

더 알아보기 (Learn more)