이전 시스템의 서드파티 플러그인 변환하기

원문 보기 위키 갱신 2026.10.07

앱에서 아직 새 프론트엔드 시스템을 지원하지 않는 서드파티 플러그인을 사용 중이거나 사용하고 싶다면, @backstage/core-compat-api의 변환 유틸리티를 사용해 플러그인을 감싸 앱에 설치할 수 있게 만드는 경우가 많아요.

출처: 문서

본문

주의

이 유틸리티의 목적은 서드파티 플러그인을 감싸기 위한 것이에요. 새 프론트엔드 시스템에 대한 지원을 직접 추가할 수 있는 자체 플러그인에는 사용하지 마세요.

레거시 플러그인 변환하기

@backstage/core-compat-api 패키지는 레거시 플러그인을 새 프론트엔드 시스템으로 변환하는 데 사용할 수 있는 convertLegacyPlugin 함수를 export해요. 이전 플러그인 인스턴스를 전달하기만 하면 새 플러그인이 반환돼요.

import { techdocsPlugin } from '@backstage/plugin-techdocs';// TechDocs is used as an example here, it already supports// the new frontend system so don't use this code directly.const convertedTechdocsPlugin = convertLegacyPlugin(techdocsPlugin, {  extensions: [],});

convertLegacyPlugin을 사용할 때는 확장 배열도 전달해야 한다는 점에 유의하세요. convertLegacyPlugin 함수는 이전 시스템의 다양한 확장 유형에 접근할 수 없고 알지 못하기 때문이에요. 대신 플러그인 인스턴스에 포함하려는 각 이전 확장을 수동으로 변환해야 해요.

레거시 확장 변환하기

위에서 언급했듯이 플러그인 인스턴스에 포함하려는 각 이전 확장을 수동으로 변환해야 해요. @backstage/core-compat-api 패키지는 이를 위해 convertLegacyPageExtension을 export하며, 최상위 페이지 확장을 새 시스템으로 변환하는 데 사용할 수 있어요. 이전 확장을 전달하기만 하면 새 확장이 반환돼요.

const convertedIndexPage = convertLegacyPageExtension(TechDocsIndexPage);

추론된 매개변수 재정의하기

convertLegacyPageExtension 같은 변환 함수는 이전 확장에서 매개변수를 추론하려고 시도하며, 특히 이전 확장의 이름을 사용해 새 확장의 이름과 라우트 경로 같은 것을 결정해요. 추론된 값이 올바르지 않은 경우 변환 함수에 자체 매개변수를 제공해야 할 수도 있어요.

const convertedIndexPage = convertLegacyPageExtension(TechDocsIndexPage, {  name: 'index',  path: '/docs',});

다른 유형의 확장

@backstage/core-compat-api는 내장 확장 유형, 즉 페이지 확장에 대한 변환 함수만 제공해요. catalog용 엔터티 콘텐츠와 카드 확장처럼 자체 확장 유형을 정의하는 플러그인이 많아요. 이 경우 이런 유형의 확장에 대한 자체 변환 함수를 제공하는 것은 플러그인 라이브러리의 몫이에요. 예를 들어 @backstage/plugin-catalog-react/alpha는 convertLegacyEntityContentExtension과 convertLegacyEntityCardExtension을 모두 제공해요.

다음은 다양한 라이브러리가 제공하는 알려진 변환 함수들이에요.

convertLegacyPageExtension - @backstage/core-compat-api
convertLegacyEntityContentExtension - @backstage/plugin-catalog-react/alpha
convertLegacyEntityCardExtension - @backstage/plugin-catalog-react/alpha

모두 합치기 (Putting it all together)

플러그인 변환기와 다양한 라이브러리의 확장 변환기를 함께 사용하면, 이제 서드파티 플러그인을 더 완전히 변환해 새 프론트엔드 시스템으로 빌드된 앱에 설치할 수 있어요.

import {  techdocsPlugin,  TechDocsIndexPage,  TechDocsReaderPage,  EntityTechdocsContent,} from '@backstage/plugin-techdocs';const convertedTechdocsPlugin = convertLegacyPlugin(techdocsPlugin, {  extensions: [    convertLegacyPageExtension(TechDocsIndexPage, {      name: 'index',      path: '/docs',    }),    convertLegacyPageExtension(TechDocsReaderPage, {      path: '/docs/:namespace/:kind/:name/*',    }),    convertLegacyEntityContentExtension(EntityTechdocsContent),  ],});const app = createApp({  features: [convertedTechdocsPlugin],});