패키지 역할 마이그레이션

원문 보기 위키 갱신 2026.10.07

패키지 역할 마이그레이션 (Package Role Migration)

The Backstage CLI has introduced the 개념 of package roles, whose purpose is to enable more powerful tooling, optimizations, and leaner package configuration.

출처: 문서

본문

Backstage CLI가 패키지 역할(package roles) 개념을 도입했습니다. 그 목적은 더 강력한 도구, 최적화, 더 간결한 패키지 구성을 가능하게 하는 것입니다. 변경에 대한 추가 배경과 정보는 원본 RFC와 이 페이지의 FAQ에서 확인할 수 있습니다.

패키지 역할은 각 패키지의 package.json에서 잘 알려진 "backstage"."role" 필드를 통해 구현됩니다. 지금까지 정의된 역할은 몇 가지이며, 사전 정의된 역할 집합 밖의 값을 사용할 수 없습니다.

모든 패키지에 역할이 갖추어지면 Backstage CLI는 각 패키지를 처리하는 방법을 자동으로 결정할 수 있습니다. 예를 들어 서로 다른 빌드 명령이 각 역할을 빌드하는 방법을 아는 단일 명령으로 대체되었습니다. 테스트 및 린트 구성도 역할을 기반으로 자동 선택되며, CLI에 모든 패키지에서 동시에 작동할 수 있는 repo 명령 범주가 새로 도입되었습니다.

패키지 역할은 Backstage 기본 저장소에서 한동안 사용되어 왔으며, 이제 모든 Backstage 프로젝트가 패키지 역할을 사용하도록 마이그레이션할 것을 권장합니다.

마이그레이션 (Migration)

마이그레이션을 최대한 매끄럽게 만들기 위해 @backstage/cli는 여러 마이그레이션 유틸리티를 제공합니다. 이를 일부 수동 검토 및 선택적 단계와 함께 사용하는 것이 대부분의 프로젝트에서 패키지 역할로 마이그레이션하기 위해 필요한 전부입니다.

마이그레이션을 시작하기 전에 @backstage/cli의 가장 최신 버전으로 업데이트했는지 확인하세요.

TL;DR, Step 1-4:

다음은 서두를 때를 위한 모든 아래 단계의 더 짧은 버전입니다.

다음 명령을 실행하세요.

yarn backstage-cli migrate package-rolesyarn backstage-cli migrate package-scriptsyarn backstage-cli migrate package-lint-configs

yarn backstage-cli repo 아래의 새 명령을 살펴보고 가능한 곳이면 그쪽으로 전환하세요. lerna 동등물보다 훨씬 빠른 경향이 있습니다.

Step 1 - 패키지 역할 추가 (Add package roles)

첫 번째 단계는 각 패키지에 "backstage"."role" 필드를 추가하는 것입니다. 물론 수동으로 할 수 있지만, 다음 명령은 프로젝트의 각 패키지 역할을 자동으로 감지하려고 시도합니다.

yarn backstage-cli migrate package-roles

자동 감지는 완벽하지 않으므로 각 패키지에 할당된 역할을 수동으로 검토하는 것이 좋습니다. 패키지 역할 정의를 참조로 사용할 수 있습니다.

Step 2 - 패키지 스크립트 마이그레이션 (Migrate package scripts)

패키지 역할로의 마이그레이션은 CLI에 새 package 명령 범주도 도입합니다. package 범주 아래의 각 명령은 package.json의 "scripts" 항목에 직접 매핑되도록 설계되었습니다. 이 명령들은 build, app:build, lint, test 같은 기존 명령을 대체합니다. 대략 다음과 같습니다.

{  "scripts": {    "start": "backstage-cli package start",    "build": "backstage-cli package build",    "lint": "backstage-cli package lint",    ...  }}

모든 패키지 역할에는 권장 스크립트의 고정 집합이 있습니다. 이 스크립트를 사용하는 것이 강력히 권장되는데, CLI의 다른 부분에서 최적화가 가능해지기 때문입니다. 다음 명령을 실행하면 모든 스크립트 사용으로 마이그레이션할 수 있습니다.

yarn backstage-cli migrate package-scripts

마이그레이션 명령은 이전 스크립트에 전달되고 있던 기존 플래그도 그대로 가져옵니다.

결국 이 정확한 스크립트 설정을 사용하고 싶지 않더라도 package 명령 사용으로 마이그레이션하는 것이 여전히 권장됩니다. 최상위 명령은 폐기되고 제거될 것이기 때문입니다. 패키지 역할도 사용하고 싶지 않다면 일부 패키지 명령에 명시적 역할을 전달할 수 있습니다. 예: yarn backstage-cli package build --role web-library.

Step 3 - 패키지 ESLint 구성 마이그레이션 (Migrate package ESLint configurations)

패키지 역할로의 전환의 일부로 단순화된 영역은 ESLint 구성입니다. 각 패키지가 원하는 구성을 선택하게 하는(그리고 틀리게 하는) 대신, 이제 패키지 역할을 활용하는 공유 구성 팩토리를 사용합니다. 새 구성 설정에 대한 자세한 내용은 빌드 시스템 문서에서 읽을 수 있습니다.

프로젝트의 모든 패키지 ESLint 구성을 마이그레이션하려면 다음 명령을 실행하세요.

yarn backstage-cli migrate package-lint-configs

이것은 @backstage/cli의 이전 구성을 확장하는 모든 기존 .eslintrc.js를 마이그레이션하고, 추가 구성을 그대로 가져옵니다.

Step 4 - `backstage-cli repo` 사용 (Use `backstage-cli repo`)

Backstage CLI는 최근 전체 모노레포에서 한 번에 작동하는 명령을 담는 새 repo 명령 범주를 도입했습니다. 이 명령들은 패키지가 역할을 사용하도록 마이그레이션되면 특히 잘 작동하는데, 매우 효과적인 최적화가 가능해지기 때문입니다. lerna 같은 도구와 비교해 이 명령을 사용하는 것이 일반적으로 훨씬 빠릅니다. yarn으로 패키지 스크립트를 호출하는 오버헤드를 피하고 여러 패키지에서 동시에 작동할 수 있기 때문입니다. repo 명령에 대한 자세한 내용은 CLI command documentation에서 읽을 수 있습니다.

마이그레이션의 이 단계를 실행하는 방식은 개발 및 CI/CD 설정이 어떻게 생겼는지에 따라 달라지므로 이전 단계만큼 잘 정의되어 있지 않습니다. 루트 package.json과 CI/CD 설정에서 다음 패턴을 찾아 교체하세요.

전체 저장소를 린트하는 명령은 필요하면 --since 플래그와 함께 yarn backstage-cli repo lint로 교체해야 합니다. 예를 들어 이것:

lerna run lint --since origin/master --

은 다음으로 교체됩니다.

backstage-cli repo lint --since origin/master

전체 저장소를 빌드하는 곳에서는 yarn backstage-cli repo build를 사용하며, 이것도 --since 플래그를 지원합니다. 여기서의 마이그레이션은 모든 패키지를 빌드하는 이유에 따라 달라지므로 조금 더 미묘합니다.
- 모든 패키지를 빌드가 가능한지 검증하기 위해 빌드한다면 backstage-cli repo build --all을 원할 것입니다. --all 플래그는 packages/app과 packages/backend 같은 번들 패키지도 빌드되어야 함을 나타냅니다. 모든 패키지를 빌드할 필요가 없도록 CI에서 --since 플래그와 함께 사용하세요.
- 모든 패키지를 게시하기 위해 빌드한다면 backstage-cli repo build로 충분합니다. 게시되는 모든 패키지를 빌드하기 때문입니다.
- 모든 패키지를 배포하기 위해 빌드한다면 repo 명령을 전혀 사용하고 싶지 않을 것입니다. 배포하려는 패키지에서 yarn build를 호출하세요. 예를 들어 docker 호스트 빌드로 백엔드를 배포한다면 packages/backend 안에서 yarn build를 호출하는 것으로 충분합니다. 표준 @backstage/create-app에는 루트에서 백엔드를 빌드하는 단축형 yarn build:backend도 있습니다.

FAQ

패키지 역할이 도입된 이유는 무엇인가요? (Why were package roles introduced?)

구성을 간결하게 유지하고, 더 많은 유틸리티와 도구를 허용하며, 빌드 시스템에서 최적화를 가능하게 하기 위해서입니다. 이유에 대한 자세한 내용은 원본 RFC에서 읽을 수 있습니다.

패키지 역할 사용으로 마이그레이션해야 하나요? (Do I have to migrate to using package roles?)

짧은 답 - 예.

긴 답 - 대부분 그렇습니다. 명령 호출이나 구성에서 역할을 명시적으로 선언하면 패키지 역할을 선언하지 않아도 됩니다. 예를 들어 app:build 명령은 사라지지만, package.json에 역할을 선언하고 싶지 않다면 package build --role frontend로 교체할 수 있습니다. 다만 패키지 역할 선언을 강력히 권장합니다.

기존 역할 중 어느 것도 적용되지 않는 패키지가 있습니다 (I have a package where none of the existing roles apply)

web-library, node-library, common-library 역할은 대부분의 사용 사례를 다루어야 하는 범용 역할입니다. 그 역할 중 어느 것도 맞지 않는다고 생각되면 Backstage 저장소에 이슈를 열고 새 역할 추가를 제안해 주세요.

게시된 패키지에 역할을 포함해야 하나요? (Should I include the role in published packages?)

예. 현재 역할을 소비하는 것은 없지만, 게시된 패키지에 역할이 포함되면 향후 도구가 사용자에게 더 나은 경험을 제공할 수 있을 것 같습니다.

패키지 역할 마이그레이션