새 프론트엔드 플러그인 스캐폴딩하기
Backstage 리포지토리의 루트 디렉터리에서 명령어를 실행해 새 프론트엔드 플러그인 패키지를 만드는 방법을 알려드려요.
출처: 문서
본문
Backstage 리포지토리의 루트 디렉터리에서 다음 명령어를 실행해 새 프론트엔드 플러그인 패키지를 만드세요.
yarn new --select frontend-plugin --option pluginId=todo --option owner=
new 명령어에 전달한 플래그와 루트 package.json의 설정에 따라 @internal/plugin-todo 같은 이름을 가진 새 NPM 패키지가 만들어져요. 더 많은 옵션은 CLI 문서를 참고하세요.
플러그인을 만드는 데는 잠시 시간이 걸려요. 명령어가 끝나면 플러그인 ID에 따라 plugins/todo에 새 폴더가 생기며, 그 구조는 다음과 같아요.
plugins/todo/├── dev/ # 독립 실행형 dev 서버 설정├── src/│ ├── components/│ │ ├── TodoList/│ │ └── TodoPage/│ └── ... # 플러그인 정의, 라우트, 테스트└── package.json
무엇을 만들었나요?
여기 핵심 파일들을 간단히 정리한 내용이에요.
-
src/plugin.tsx— 플러그인의 핵심 정의예요.createFrontendPlugin으로 플러그인을 만들고PageBlueprint로 페이지 확장을 등록하는 곳이에요. -
src/plugin.test.ts— 플러그인 정의용 테스트예요. 플러그인과 그 확장이 올바르게 만들어졌는지 검증해요. -
src/routes.ts— 플러그인 사이를 이동할 때 쓰는 라우트 참조 정의예요. -
src/index.ts— 패키지 진입점으로, 플러그인을 기본 내보내기로 노출해요. -
src/components/TodoPage/— 메인 페이지 컴포넌트예요. 백엔드에서 todo 항목을 가져와TodoList컴포넌트로 렌더링해요. -
src/components/TodoList/—@backstage/ui로 todo 항목 테이블을 렌더링하는 프레젠테이션 컴포넌트예요. -
dev/index.tsx— 플러그인만 로드하는 독립 실행형 개발 앱이에요. 플러그인 디렉터리에서yarn start를 실행해 시작하세요. -
package.json—backstage.role필드가"frontend-plugin"으로 설정된 것을 확인하세요. 이 값이 Backstage 도구에 패키지를 어떻게 빌드하고 다룰지 알려줘요.
플러그인 검증하기
앱에서 기능 발견(feature discovery)을 활성화했다면(기본값) 플러그인이 자동으로 감지돼요. 기능 발견을 쓰지 않는다면 설치 문서에서 앱에 플러그인을 수동으로 추가하는 방법을 확인하세요. 리포지토리 루트에서 전체 앱을 시작하세요.
yarn start
그다음 브라우저에서 http://localhost:3000/todo로 이동하세요(경로는 선택한 플러그인 ID와 일치해요). 헤더와 예제 데이터가 있는 todo 페이지가 보일 거예요. 백엔드 todo 플러그인도 실행 중이라면 실제 todo 항목이 대신 표시돼요.
독립 실행형 개발 서버를 사용해 플러그인을 격리된 상태로 실행해 보세요.
yarn workspace @internal/plugin-todo start
자주 겪는 문제
플러그인 페이지가 표시되지 않는 경우
app-config.yaml에서 app.packages가 all로 설정되어 있는지 확인하세요. include/exclude 필터를 쓴다면 플러그인 패키지가 제외되지 않았는지 확인해 보세요.
yarn new가 설치 중에 실패하는 경우
먼저 리포지토리 루트에서 yarn install을 실행했는지, 그리고 Node.js 버전이 프로젝트가 요구하는 버전과 일치하는지 확인하세요.
스캐폴딩 후 TypeScript 오류가 나는 경우
리포지토리 루트에서 yarn tsc를 실행해 타입 오류를 확인하세요. 새로 만든 스캐폴드는 깨끗하게 컴파일되어야 해요. 그렇지 않다면 yarn install을 다시 실행해 보세요.