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

CLI 템플릿

원문 보기 위키 갱신

CLI 템플릿 (CLI Templates)

The backstage-cli new 명령(일반적으로 Backstage 워크스페이스에서 yarn new로 실행)은 새 플러그인, 모듈 및 라이브러리 패키지를 스캐폴딩합니다.

출처: 문서

본문

The backstage-cli new 명령(일반적으로 Backstage 워크스페이스에서 yarn new로 실행)은 새 플러그인, 모듈 및 라이브러리 패키지를 스캐폴딩합니다. 사용 가능한 템플릿 목록을 제시하고 짧은 프롬프트 집합을 진행시킨 다음 패키지를 생성하고, 의존성을 연결하고, 워크스페이스에 등록합니다.

내장 템플릿 (Built-in templates)

즉시 사용 가능한 다음 템플릿이 포함됩니다.

Template Description
frontend-plugin 새 프런트엔드 플러그인
frontend-plugin-module 기존 프런트엔드 플러그인을 확장하는 새 프런트엔드 모듈
legacy-frontend-plugin 새 프런트엔드 플러그인 (레거시 시스템)
backend-plugin 새 백엔드 플러그인
backend-plugin-module 기존 백엔드 플러그인을 확장하는 새 백엔드 모듈
plugin-web-library 새 웹 라이브러리 플러그인 패키지
plugin-node-library 새 Node.js 라이브러리 플러그인 패키지
plugin-common-library 새 동형 공통 플러그인 패키지
web-library 웹 환경용 공유 기능을 내보내는 라이브러리 패키지
node-library Node.js 환경용 공유 기능을 내보내는 라이브러리 패키지
cli-module Backstage CLI에 명령을 추가하는 CLI 모듈
catalog-processor-module 소프트웨어 카탈로그용 Processor 모듈
catalog-provider-module 소프트웨어 카탈로그용 Entity Provider 모듈
scaffolder-backend-module @backstage/plugin-scaffolder-backend용 사용자 지정 작업을 내보내는 모듈
scaffolder-field-extension-module Backstage Scaffolder용 사용자 지정 필드 확장
permission-policy-module permission-backend 플러그인에 사용자 지정 권한 정책을 제공하는 백엔드 모듈
search-collator-module Backstage Search용 Search Collator 모듈

구성 (Configuration)

yarn new의 동작은 루트 package.json을 통해 구성할 수 있습니다.

{  "name": "root",  "backstage": {    "cli": {      "new": {        "globals": {          "license": "MIT",          "namePrefix": "@my-org/"        }      }    }  }}
  • globals - 생성된 모든 패키지와 플러그인에 대한 입력을 구성합니다.
  • version - 생성된 모든 패키지의 package.json에서 version 필드 값을 설정합니다. 기본값은 0.1.0입니다.
  • license - 생성된 모든 패키지의 package.json에서 license 필드 값을 설정합니다. 기본값은 Apache-2.0입니다.
  • private - 생성된 모든 패키지의 package.json에서 private 필드 값을 설정합니다. 기본값은 true입니다.
  • publishRegistry - 생성된 모든 패키지의 package.json에서 publishConfig.registry 필드 값을 설정합니다.
  • namePrefix - 전체 패키지 이름을 생성하는 데 사용되는 접두사입니다. 기본값은 @internal/입니다.
  • namePluginInfix - 플러그인 패키지의 전체 패키지 이름을 생성하는 데 사용되는 중위사입니다. 기본값은 plugin-입니다.
  • templates - 사용자 지정 템플릿을 지정합니다.
  • 자세한 내용은 Installing custom templates 및 Creating your own CLI templates를 참조하세요.

생성된 패키지 이름은 namePrefix 및 namePluginInfix globals와, 패키지 역할과 사용자 입력에서 파생된 "base name"을 기반으로 합니다. 플러그인 패키지의 최종 패키지 이름은 <namePrefix><namePluginInfix><baseName>이 되고, 다른 패키지는 <namePrefix><baseName>이 됩니다.

예를 들어 플러그인 프런트엔드 패키지의 이름이 @acme/backstage-plugin-<pluginId>로 끝나게 하려면 다음 구성을 사용해야 합니다.

{  "name": "root",  "backstage": {    "cli": {      "new": {        "globals": {          "namePrefix": "@acme/",          "namePluginInfix": "backstage-plugin-"        }      }    }  }}

사용자 지정 템플릿 설치 (Installing custom templates)

사용자 지정 템플릿은 로컬 디렉터리에서 설치할 수 있습니다. 템플릿을 설치하려면 루트 package.json의 backstage.cli.new.templates 구성 배열에 추가합니다.

{  "name": "root",  "backstage": {    "cli": {      "new": {        "templates": ["./templates/custom-plugin"]      }    }  }}

templates 배열의 각 항목은 portable-template.yaml 파일을 포함하는 디렉터리를 가리키는 상대 경로여야 합니다. 경로가 ./로 시작하면 그대로 사용되고, 그렇지 않으면 node_modules 내부의 모듈로 해석됩니다.

templates 배열을 정의하면 기본 템플릿 집합이 재정의됩니다. Backstage CLI의 내장 템플릿 중 하나를 계속 사용하려면 @backstage/cli-module-new 패키지 내에서 직접 참조할 수 있습니다. 내장 템플릿의 전체 목록은 다음과 같습니다.

{  "name": "root",  "backstage": {    "cli": {      "new": {        "templates": [          "@backstage/cli-module-new/templates/frontend-plugin",          "@backstage/cli-module-new/templates/frontend-plugin-module",          "@backstage/cli-module-new/templates/legacy-frontend-plugin",          "@backstage/cli-module-new/templates/backend-plugin",          "@backstage/cli-module-new/templates/backend-plugin-module",          "@backstage/cli-module-new/templates/plugin-web-library",          "@backstage/cli-module-new/templates/plugin-node-library",          "@backstage/cli-module-new/templates/plugin-common-library",          "@backstage/cli-module-new/templates/web-library",          "@backstage/cli-module-new/templates/node-library",          "@backstage/cli-module-new/templates/cli-module",          "@backstage/cli-module-new/templates/catalog-processor-module",          "@backstage/cli-module-new/templates/catalog-provider-module",          "@backstage/cli-module-new/templates/scaffolder-backend-module",          "@backstage/cli-module-new/templates/scaffolder-field-extension-module",          "@backstage/cli-module-new/templates/permission-policy-module",          "@backstage/cli-module-new/templates/search-collator-module"        ]      }    }  }}

note

이전 @backstage/cli/templates/* 경로는 이전 버전과의 호환성을 위해 여전히 지원되며 @backstage/cli-module-new/templates/*로 자동 재작성됩니다.

자체 CLI 템플릿 만들기 (Creating your own CLI templates)

각 템플릿은 자체 디렉터리에 있으며 템플릿을 설명하는 portable-template.yaml 파일이 있어야 합니다. 템플릿 디렉터리는 생성된 패키지에 템플릿 처리되거나 복사되어야 하는 파일도 포함할 수 있습니다.

프로젝트 어딘가의 새 디렉터리에 portable-template.yaml을 만드는 것부터 시작하세요. 이 예시에서는 ./templates/custom-plugin/portable-template.yaml을 사용합니다.

in templates/custom-plugin/portable-template.yaml

name: custom-pluginrole: frontend-plugindescription: Description of my CLI template # optionalvalues: # optional  pluginVar: '{{ camelCase pluginId }}Plugin'

다음 속성이 지원됩니다.

  • name (필수) - 사용자가 선택하는 데 사용하는 템플릿의 이름입니다.
  • role (필수) - package role과 유사한 템플릿의 역할입니다. 자세한 내용은 Template Roles를 참조하세요.
  • description - 이 템플릿이 생성하는 패키지 유형에 대한 설명입니다.
  • values - 템플릿 처리 중에 존재할 추가 값의 맵입니다. 값 자체도 템플릿 처리되며 다른 값을 참조할 수 있습니다. 키가 pluginId 같은 사용자 프롬프트와 일치하면 사용자에게 묻는 대신 값이 직접 사용됩니다.

다음으로 템플릿의 일부로 만들 다른 파일을 같은 디렉터리에 추가하세요. .hbs 확장자를 가진 파일을 제외한 모든 파일이 그대로 복사됩니다. .hbs 파일은 Handlebars 템플릿으로 처리되어 portable-template.yaml 파일의 값과 pluginId 같은 추가 프롬프트로 렌더링됩니다. 예를 들어 다음 내용의 src/index.ts 파일을 만들 수 있습니다.

in templates/custom-plugin/src/index.ts.hbs

export function getPluginId() {  return '{{ pluginId }}';}

더 많은 예시를 보려면 모든 기본 템플릿과 yaml 파일을 여기에서 찾을 수 있습니다.

템플릿이 준비되면 구성에 추가하고, 이제 yarn new를 실행할 때 선택할 수 있어야 합니다.

템플릿 역할 (Template Roles)

템플릿 yaml 파일의 role 속성은 템플릿에 대해 어떤 입력이 수집될지, 그리고 새 패키지가 생성된 후 어떤 작업이 수행될지 결정하는 데 사용됩니다. 다음 역할이 지원됩니다.

Role Prompts Output Directory Additional Actions
frontend-plugin pluginId plugins packages/app에 의존성 추가 및 packages/backend/src/App.tsx에 항목 추가
frontend-plugin-module pluginId, moduleId plugins packages/app에 의존성 추가
backend-plugin pluginId plugins packages/backend에 의존성 추가 및 packages/backend/src/index.ts에 항목 추가
backend-plugin-module pluginId, moduleId plugins packages/backend에 의존성 추가 및 packages/backend/src/index.ts에 항목 추가
web-library name packages 없음
node-library name packages 없음
common-library name packages 없음
plugin-web-library pluginId plugins 없음
plugin-node-library pluginId plugins 없음
plugin-common-library pluginId plugins 없음

의존성 버전 관리 (Dependency Versioning)

yarn new 명령은 저장소에 Backstage Yarn 플러그인이 설치되어 있는지 자동으로 감지하고 그에 따라 의존성 버전 관리를 조정합니다.

Backstage Yarn 플러그인(.yarnrc.yml로 감지)이 설치되면 yarn new는 모든 @backstage/* 의존성에 backstage:^ 범위를 생성합니다. 이는 새 패키지가 backstage.json 파일에 정의된 것과 동일한 Backstage 버전을 사용하도록 보장합니다.

플러그인이 설치되지 않으면 yarn new는 모든 의존성에 표준 npm 버전 범위(예: ^1.0.0)를 사용하여 이전 버전과의 호환성을 유지합니다.

플러그인 설치 여부와 관계없이 yarn.lock 파일에서 발견된 workspace: 범위가 항상 backstage:^과 npm 범위보다 우선합니다. 이는 모노레포 내 패키지가 가능할 때 워크스페이스 연결을 계속 사용하도록 보장합니다.

더 알아보기 (Learn more)