모듈 개요

원문 보기 위키 갱신 2026.10.07

모듈 개요 (Overview)

Backstage CLI는 독립적인 CLI 모듈 집합으로 구축되며, 각 모듈은 관련 명령 그룹을 제공합니다.

출처: 문서

본문

Backstage CLI는 독립적인 CLI 모듈 집합으로 구축되며, 각 모듈은 관련 명령 그룹을 제공합니다. 이 모듈형 아키텍처를 통해 어떤 명령을 사용할 수 있는지 선택하고 자체 명령을 추가할 수 있습니다.

기본 모듈 (Default modules)

즉시 사용 시 CLI는 기본값으로 @backstage/cli-defaults와 함께 제공되며, 이는 다음 모듈을 번들합니다.

Module	Package	Commands
Auth	`@backstage/cli-module-auth`	`auth login`, `auth logout`, `auth show`, `auth list`, `auth print-token`, `auth select`
Actions	`@backstage/cli-module-actions`	`actions list`, `actions execute`, `actions sources add`, `actions sources list`, `actions sources remove`
Build	`@backstage/cli-module-build`	`package build`, `package start`, `package bundle`, `package clean`, `package prepack`, `package postpack`, `repo build`, `repo start`, `repo clean`, `build-workspace`
Config	`@backstage/cli-module-config`	`config:docs`, `config:print`, `config:check`, `config:schema`
GitHub	`@backstage/cli-module-github`	`create-github-app`
Info	`@backstage/cli-module-info`	`info`
Lint	`@backstage/cli-module-lint`	`package lint`, `repo lint`
Maintenance	`@backstage/cli-module-maintenance`	`repo fix`, `repo list-deprecations`
Migrate	`@backstage/cli-module-migrate`	`versions:bump`, `versions:migrate`, `migrate package-roles`, `migrate package-scripts`, `migrate package-exports`, `migrate package-lint-configs`, `migrate react-router-deps`
New	`@backstage/cli-module-new`	`new`
Test	`@backstage/cli-module-test-jest`	`repo test`, `package test`
Translations	`@backstage/cli-module-translations`	`translations export`, `translations import`
Yarn Package Manager	`@backstage/cli-module-package-manager-yarn`	`pm verify-patches`

각 모듈 이름은 옵션과 예시를 포함한 전체 명령 문서가 있는 전용 페이지로 연결됩니다. 모든 명령의 빠른 참조 색인은 commands 페이지를 참조하세요.

모듈 발견 작동 방식 (How module discovery works)

CLI가 시작되면 프로젝트 루트의 package.json에서 모든 의존성과 개발 의존성을 스캔합니다. 각 의존성에 대해 패키지 자체의 package.json에 backstage.role이 "cli-module"로 설정되어 있는지 확인합니다. 설정되어 있다면 모듈이 로드되고 해당 명령이 사용 가능해집니다.

프로젝트 의존성에서 CLI 모듈이 발견되지 않으면 CLI는 @backstage/cli-defaults를 가져오는 것으로 폴백하고 폐기 경고를 출력합니다. 이 폴백은 향후 릴리스에서 제거될 예정입니다. 경고를 피하려면 루트 package.json에 @backstage/cli-defaults를 개발 의존성으로 추가하거나, 개별 @backstage/cli-module-* 패키지를 설치하세요.

기본 모듈 사용자 정의 (Customizing the default modules)

모듈 재정의 (Overriding a module)

프로젝트 루트에 대체 모듈을 직접 의존성으로 설치해 기본 모듈 중 하나 이상을 재정의할 수 있습니다. 개별적으로 설치된 모듈이 @backstage/cli-defaults의 모듈과 충돌하면, 개별적으로 설치된 모듈이 우선하고 충돌하는 기본 모듈은 조용히 건너뜁니다.

예를 들어 @backstage/cli-module-build와 같은 명령 경로를 등록하는 내부 @mycompany/cli-module-build를 게시했다면, 루트 package.json에 추가하면 기본 빌드 모듈 대신 사용됩니다.

package.json

{  "devDependencies": {    "@backstage/cli": "...",    "@mycompany/cli-module-build": "..."  }}

모듈 하위 집합 사용 (Using a subset of modules)

특정 모듈만 필요하다면 @backstage/cli-defaults에 의존하는 대신 개별적으로 설치할 수 있습니다. CLI는 동일한 의존성 스캔 메커니즘으로 이를 발견합니다.

package.json

{  "devDependencies": {    "@backstage/cli": "...",    "@backstage/cli-module-build": "...",    "@backstage/cli-module-lint": "...",    "@backstage/cli-module-test-jest": "..."  }}

이 예시에서는 빌드, 린트, 테스트 명령만 사용할 수 있습니다.

사용자 지정 모듈 추가 (Adding custom modules)

기본 모듈과 함께 자체 CLI 모듈을 추가할 수 있습니다. package.json에 backstage.role이 "cli-module"로 설정되어 있고 의존성으로 나열된 모든 패키지가 자동으로 발견됩니다. 전체 가이드는 Building Custom CLI Modules를 참조하세요.

아키텍처 (Architecture)

CLI 모듈 시스템은 여러 패키지에 걸쳐 구현됩니다.

@backstage/cli — 주요 CLI 진입점입니다. 모듈을 발견하는 CliInitializer와 프로젝트 의존성을 스캔하는 discoverCliModules 함수를 포함합니다.
@backstage/cli-node — CLI 모듈 구축을 위한 공개 API를 제공합니다: createCliModule, runCli, 그리고 CliModule, CliCommand, CliCommandContext 타입.
@backstage/cli-common — 경로 해석과 자식 프로세스 관리를 위한 최소 공유 유틸리티로, CLI, 백엔드, create-app에서 사용됩니다.
@backstage/cli-defaults — 13개의 기본 모듈을 모두 배열로 재내보내는 집계 패키지입니다.