본문 바로가기
WIKI 기술 지식 베이스

Build 모듈

원문 보기 위키 갱신

The build module (@backstage/cli-module-build)은 개별적으로 그리고 저장소 전체에서 Backstage 패키지를 빌드, 시작, 패키징하는 작업을 처리합니다.

출처: 문서

본문

The build module (@backstage/cli-module-build)은 개별적으로 그리고 저장소 전체에서 Backstage 패키지를 빌드, 시작, 패키징하는 작업을 처리합니다.

빌드 시스템 자체에 대한 자세한 내용은 Build System 문서를 참조하세요.

repo start

로컬 개발을 위해 프로젝트의 패키지 집합을 시작합니다. 인수나 옵션으로 명시적 패키지가 나열되지 않으면 패키지 역할을 기준으로 패키지가 선택됩니다. 단일 프런트엔드 및/또는 백엔드 패키지 집합이 발견되면 시작됩니다. 여러 일치 항목이 있으면 packages/app 및 packages/backend 디렉터리가 선호됩니다. 일치 항목이 없으면 명령은 대신 단일 플러그인 프런트엔드 및/또는 백엔드 패키지를 시작할 것으로 기대합니다.

선택된 패키지의 package.json에 있는 start 스크립트의 --config 옵션은 이 명령에 --config 옵션이 제공되지 않는 한 선택되어 사용됩니다. 제공되면 그 옵션이 대신 사용됩니다.

선택된 백엔드 패키지의 package.json에 있는 start 스크립트의 --require 옵션은 선택되어 사용됩니다.

Usage: backstage-cli repo start [options] [packageNameOrPath...]Starts packages in the repo for local developmentArguments:  packageNameOrPath     Run the specified packages instead of the defaults.Options:  --plugin <pluginId>   Start the dev entry-point for any matching plugin package in the repo (default: [])  --config <path>       Config files to load instead of app-config.yaml (default: [])  --inspect [host]      Enable debugger in Node.js environments. Applies to backend package only  --inspect-brk [host]  Enable debugger in Node.js environments, breaking before code starts. Applies to backend package only  --require <path>      Add a --require argument to the node process. Applies to backend package only  --link <path>         Link an external workspace for module resolution

repo build

기본적으로 번들 패키지, 즉 'frontend' 또는 'backend' 역할을 가진 패키지를 제외하고 프로젝트의 모든 패키지를 빌드합니다.

Usage: backstage-cli repo build [options]Build packages in the project, excluding bundled app and backend packages.Options:  --all          Build all packages, including bundled app and backend packages.  --since <ref>  Only build packages and their dev dependents that changed since the specified ref

repo clean

프로젝트의 모든 패키지에서 캐시 및 출력 디렉터리를 제거합니다.

Usage: backstage-cli repo clean [options]Delete cache and output directories

package start

로컬 개발을 위해 패키지를 시작합니다. 자세한 내용은 빌드 시스템 번들링 섹션의 프런트엔드 및 백엔드 개발 부분을 참조하세요.

Usage: backstage-cli package start [options]Start a package for local developmentOptions:  --config <path>     Config files to load instead of app-config.yaml (default: [])  --role <name>       Run the command with an explicit package role  --check             Enable type checking and linting if available  --require <path>    Add a --require argument to the node process  --link <path>       Link an external workspace for module resolution  --entrypoint <path> Entry directory path (uses index file) or entry file path (without extension). Defaults to "dev"  --inspect [host]    Enable the Node.js inspector, optionally at a specific host:port  --inspect-brk [host] Enable the Node.js inspector and break before user code starts

package build

역할을 기반으로 개별 패키지를 빌드합니다. 자세한 내용은 빌드 시스템의 building 및 bundling 섹션을 참조하세요.

Usage: backstage-cli package build [options]Build a package for production deployment or publishingOptions:  --role <name>              Run the command with an explicit package role  --minify                   Minify the generated code. Does not apply to app package (app is minified by default).  --skip-build-dependencies  Skip the automatic building of local dependencies. Applies to backend packages only.  --stats                    If bundle stats are available, write them to the output directory. Applies to app packages only.  --config <path>            Config files to load instead of app-config.yaml. Applies to app packages only. (default: [])  --module-federation        Build a package as a module federation remote. Applies to frontend plugin packages only.

package bundle

실험적 (Experimental)

이 명령은 실험적이며 향후 릴리스에서 폐기 기간 없이 파괴적인 변경을 받을 수 있습니다. 기본 --help 출력에서 숨겨져 있습니다.

동적 로딩을 위해 플러그인을 번들합니다. 독립적으로 배포하고 Backstage 애플리케이션이 동적으로 로드할 수 있는 자족적 플러그인 패키지를 만듭니다. 백엔드와 프런트엔드 플러그인을 모두 지원합니다.

일반 빌드와 달리 bundle 명령은 다음을 수행합니다.

  • 완전한 자족적 플러그인 산출물을 만듭니다.
  • 모듈 페더레이션 자산을 생성하거나(프런트엔드), 로컬 workspace:^ 의존성을 먼저 빌드하고(yarn pack으로) 패킹하며 플러그인의 개인 node_modules에 플러그인 의존성을 포함합니다(백엔드).
  • 플러그인 관련 패키지에서만 구성 스키마를 생성합니다.
  • 플러그인이 유효한 동적 로딩 진입점을 내보내는지 검증합니다(백엔드만).

사용법 (Usage)

# Bundle the current package (output: ./bundle/)yarn backstage-cli package bundle# Bundle to a specific directory (output: ../dynamic-plugins/<mangled-package-name>/)yarn backstage-cli package bundle --output-destination ../dynamic-plugins# Override the bundle subdirectory nameyarn backstage-cli package bundle --output-name my-plugin-bundle# Clean output before bundlingyarn backstage-cli package bundle --clean# Skip building for the plugin and its local dependenciesyarn backstage-cli package bundle --no-build# Skip dependency installation and entrypoint validationyarn backstage-cli package bundle --no-install# Stream detailed output from build, pack, and install stepsyarn backstage-cli package bundle --verbose# Use a pre-built dist workspace for batch bundling.# First, create the workspace with:#   backstage-cli build-workspace <output-dir> [packages...] --alwaysPack# Then pass <output-dir> as --pre-packed-dir:yarn backstage-cli package bundle --pre-packed-dir ../dist-workspace

옵션 (Options)

Usage: backstage-cli package bundle [options]Bundle a plugin for dynamic loadingOptions:  --output-destination <dir>  Directory in which the bundle subdirectory is created.                              Defaults to the current package directory.  --output-name <name>        Name of the bundle subdirectory. Defaults to "bundle" when                              output stays in the package directory, or to the mangled                              package name (e.g. myorg-plugin-foo) when                              --output-destination is specified.  --clean                     Clean the output directory before bundling  --no-build                  Skip building packages (assumes they are already built)  --no-install                Skip dependency installation and entrypoint validation.  --verbose                   Stream detailed output from internal steps (build, pack,                              install) to the console. Without this flag, output is                              captured to per-step log files and only shown on error.  --pre-packed-dir <dir>      Path to a pre-built dist workspace (from                              build-workspace --alwaysPack). Skips local dependency                              packing and uses pre-packed packages directly. For frontend                              plugins, this also enables yarn.lock generation for SBOM.

출력 계약 (Output contract)

번들 출력은 독립 실행 단위로 배포할 수 있는 디렉터리입니다. 번들 소비자(@backstage/backend-dynamic-feature-service 또는 @backstage/frontend-dynamic-feature-loader 같은)는 다음 보장에 의존할 수 있습니다.

모든 번들:

  • 동적 로딩을 위해 구성된 진입점이 있는 번들 루트의 package.json. backstage.role와 files 필드는 소스 패키지에서 보존됩니다.
  • 빌드된 플러그인 코드를 포함하는 dist/ 디렉터리.
  • (구성 스키마가 적용될 때) 플러그인, 로컬 워크스페이스 의존성, 타사 의존성에서 수집된 스키마를 포함하는 dist/.config-schema.json 파일. 관련 없는 Backstage 패키지의 스키마는 제외됩니다.
  • package.json에 scripts나 devDependencies가 없습니다.

백엔드 플러그인 (backend-plugin, backend-plugin-module):

  • 소스 잠금 파일의 정확한 버전에 고정된 모든 프로덕션 의존성(로컬 워크스페이스 의존성 포함)을 가진 node_modules/ 디렉터리.
  • package.json에서 bundleDependencies가 true로 설정됩니다.

프런트엔드 플러그인 (frontend-plugin, frontend-plugin-module):

  • main이 dist/remoteEntry.js (Module Federation 원격 진입점)을 가리킵니다.
  • 타입 선언이 있으면 types가 dist/@mf-types/index.d.ts를 가리킵니다.
  • 내장된 node_modules/ 디렉터리가 없습니다.

환경 변수 (Environment variables)

bundle 명령은 backstage:^ 버전 지정자를 해석하기 위해 Backstage yarn 플러그인과 동일한 환경 변수를 지원합니다.

  • BACKSTAGE_MANIFEST_FILE: 로컬 매니페스트 파일의 경로 (오프라인 사용용)
  • BACKSTAGE_VERSIONS_BASE_URL: 릴리스 매니페스트 가져오기를 위한 사용자 지정 기본 URL

지원되는 패키지 역할 (Supported package roles)

bundle 명령은 다음 역할을 가진 패키지를 지원합니다.

  • backend-plugin
  • backend-plugin-module
  • frontend-plugin
  • frontend-plugin-module

package clean

캐시 디렉터리를 제거합니다.

Usage: backstage-cli package clean [options]Delete cache directories

package prepack

이 명령은 모든 패키지에서 scripts.prepack로 추가해야 합니다. package.json 내부 필드에 대한 패키징·게시 시간 재정의를 활성화합니다. 자세한 내용은 빌드 시스템 publishing 섹션을 참조하세요.

Usage: backstage-cli package prepack [options]Prepares a package for packaging before publishing

package postpack

이것은 모든 패키지에서 scripts.postpack으로 추가해야 합니다. prepack 명령을 호출하기 전의 package.json 상태로 복원합니다.

Usage: backstage-cli package postpack [options]Restores the changes made by the prepack command

build-workspace

각 패키지의 패키징된 프로덕션 버전을 사용해 워크스페이스의 미러를 빌드합니다. 본질적으로 포함된 각 패키지에서 yarn pack을 호출하고 결과 아카이브를 대상 workspace-dir에 푸는 것입니다.

Usage: backstage-cli build-workspace [options] <workspace-dir> [packages...]Options:  --alwaysPack  Force workspace output to be a result of running `yarn pack` on                each package (warning: very slow)

--alwaysPack을 사용하면 출력 디렉터리를 backstage-cli package bundle --pre-packed-dir에 전달하여 같은 모노레포의 여러 플러그인 일괄 번들링을 빠르게 할 수 있습니다.

더 알아보기 (Learn more)