패키지 메타데이터

원문 보기 위키 갱신 2026.10.07

패키지 메타데이터 (Package Metadata)

The package.json 파일은 JavaScript 패키지에 대한 메타데이터를 포함하는 JSON 파일입니다. NPM 생태계에서 확장되는 Node.js 표준이며, NPM이나 유사한 패키지 레지스트리에 게시되는 모든 패키지에 필요합니다.

출처: 문서

본문

알려진 메타데이터 필드 (Known Metadata Fields)

이 섹션은 Backstage 생태계에서 중요한 역할을 하는 알려진 package.json 메타데이터 필드를 문서화합니다.

NPM이 정의한 모든 필드는 Backstage 생태계가 상속합니다. 아래 목록은 추가 정보가 있는 표준 필드만 포함합니다.

`name`

NPM이 정의한 대로 패키지의 이름입니다. 또한 Backstage 생태계에 게시되는 패키지에 대해서는 다음 명명 체계를 강력히 권장합니다.

먼저 조직이나 패키지 모음에 고유하면서도 Backstage 생태계 안에 위치시키는 패키지 이름 접두사를 선택하세요. 예: @example/backstage, @example-backstage/, example-backstage. 이 접두사는 플러그인의 일부인지 여부와 관계없이 게시하는 모든 패키지에서 사용해야 합니다.

플러그인의 일부가 아닌 모든 패키지는 접두사와 함께 설명적인 이름을 사용해야 합니다. 예: @example/backstage-components 또는 @example/backstage-foo-client.

플러그인 패키지의 경우 플러그인 ID도 선택하고 접두사에 plugin-<pluginId>를 추가해야 하며, 패키지 역할에 기반한 접미사도 추가합니다.

<prefix>-plugin-<pluginId>: 플러그인의 주요 프런트엔드 코드.
<prefix>-plugin-<pluginId>-module-<name>: 프런트엔드 플러그인 패키지와 관련된 선택적 모듈.
<prefix>-plugin-<pluginId>-backend: 플러그인의 주요 백엔드 코드.
<prefix>-plugin-<pluginId>-backend-module-<name>: 백엔드 플러그인 패키지와 관련된 선택적 모듈.
<prefix>-plugin-<pluginId>-react: 플러그인 자체와 타사 프런트엔드 플러그인 또는 모듈이 의존할 수 있는 공유 위젯, 훅 등.
<prefix>-plugin-<pluginId>-node: 플러그인 백엔드 자체와 타사 백엔드 플러그인 또는 모듈이 의존할 수 있는 백엔드용 유틸리티.
<prefix>-plugin-<pluginId>-common: 플랫폼 독립적인 모델, 클라이언트, 유틸리티가 있는 동형 패키지로, 위 패키지 모두 또는 타사 플러그인·모듈이 의존할 수 있음.

예를 들어 poetry 플러그인의 프런트엔드 패키지는 @example/backstage-plugin-poetry라고 하고, 같은 플러그인의 백엔드 패키지는 @example/backstage-plugin-poetry-backend라고 할 수 있습니다.

프로젝트의 일부가 아닌 기존 패키지의 모듈을 만드는 경우 모듈이 대상으로 하는 패키지의 플러그인 ID와 함께 같은 접두사를 사용해야 합니다. 예를 들어 @backstage/plugin-catalog-backend의 poetry 공급자 모듈을 만든다면 @example/backstage-plugin-catalog-backend-module-poetry-provider라고 할 수 있습니다.

`repository`

NPM이 정의한 대로 패키지 소스 코드의 위치입니다.

이 필드는 backstage-cli repo fix --publish 명령으로 생성할 수 있습니다. 유일한 요구 사항은 워크스페이스 루트의 package.json에 repository 필드가 문서화되어 있다는 것입니다.

`main`

NPM이 정의한 대로 패키지의 기본 진입점입니다. 표준 Backstage 설정에서 이는 로컬 개발용 진입점, 일반적으로 src/index.ts를 가리켜야 합니다. 이 필드는 module과 types 같은 다른 진입점 필드와 함께 배포용 패키징 시 다시 작성됩니다. 이 과정에 대해 더 자세히 알아보려면 publishing 섹션을 참조하세요. 또한 백엔드 프로덕션 빌드에도 사용됩니다.

`exports`

Node.js가 정의한 대로 패키지의 내보내기입니다. 이 필드는 패키지의 진입점을 정의하는 데 사용됩니다. 다른 진입점 필드와 마찬가지로 내보내기는 로컬 개발용 진입점을 가리켜야 합니다. 배포용 패키징 시 다시 작성됩니다. 자세한 내용은 sub-path exports 섹션을 참조하세요.

`typesVersions`

이 필드는 TypeScript가 정의한 대로 패키지의 버전별 타입 진입점을 지정하는 데 사용되며 exports 필드의 동등물로 사용됩니다. TypeScript는 exports 필드의 타입 선언을 지원하지만 tsconfig.json의 moduleResolution 옵션이 node16 또는 bundler로 설정되어야 하며, 현재 Backstage 생태계는 이를 지원하지 않습니다.

이 필드는 backstage-cli repo fix 명령으로 생성할 수 있습니다. 먼저 exports 필드를 소스 필드를 가리키도록 채우면 typesVersions를 생성하는 데 사용됩니다.

`sideEffects`

이 필드는 프런트엔드 빌드에 이 패키지를 번들링할 때 트리 셰이킹을 통해 미사용 코드를 제거해도 안전한지 선언하며, 예를 들어 WebPack이 정의합니다.

이 필드는 backstage-cli repo fix 명령으로 생성할 수 있습니다. Backstage 프런트엔드 패키지는 일반적으로 어떤 부작용도 없어야 하므로 모든 프런트엔드 패키지에 대해 기본적으로 false로 설정됩니다. 패키지에 부작용이 있다면 이 필드를 명시적으로 true로 설정할 수 있습니다.

`scripts`

NPM이 정의한 대로 패키지 스크립트입니다. Backstage CLI는 표준 스크립트 집합을 제공하며, 자세한 내용은 build system 섹션에서 읽을 수 있습니다. 스크립트 전체 목록은 다음과 같습니다.

"scripts": {  "start": "backstage-cli package start",  "build": "backstage-cli package build",  "lint": "backstage-cli package lint",  "test": "backstage-cli package test",  "clean": "backstage-cli package clean",  "prepack": "backstage-cli package prepack",  "postpack": "backstage-cli package postpack"}

`configSchema`

defining configuration 섹션에 설명된 대로 패키지의 Backstage 구성 스키마입니다.

`backstage`

이 필드는 Backstage 특정 메타데이터 필드 모음입니다. 모든 Backstage 패키지에 필요하며, 이 필드를 정의하는 모든 패키지는 Backstage 생태계의 일부로 간주됩니다. 이 모음의 모든 하위 필드는 아래에 정의됩니다.

`backstage.role`

이 필드는 Backstage 생태계에서 패키지의 역할을 정의합니다. 빌드 과정과 런타임 동작 모두에 영향을 줄 수 있으며, 소비자에게 패키지의 의도된 용도를 알려줍니다. 이 필드에 대한 자세한 내용은 package roles 섹션을 참조하세요.

`backstage.pluginId`

플러그인의 일부인 모든 패키지에 대해 이 필드는 플러그인 ID로 설정되어야 합니다. 이는 패키지 구현에서 createPlugin, createBackendPlugin 또는 createBackendModule 함수에 전달할 것과 같은 ID입니다. 또한 name 섹션에서 설명한 ID와 동일합니다.

이 필드는 backstage-cli repo fix --publish 명령으로 생성할 수 있습니다. 플러그인 ID는 패키지 이름과 역할에서 추론됩니다. 패키지 이름이 실제로 플러그인의 일부가 아니지만 이름에 plugin-*가 있다면 이 필드를 명시적으로 null로 설정할 수 있습니다.

이 필드의 존재는 게시를 위해 패키지를 준비하는 데 사용되는 backstage-cli package prepack 명령이 확인합니다. 이 요구 사항에 대한 자세한 내용은 published packages에 대한 메타데이터 섹션을 참조하세요.

`backstage.features`

이 필드는 패키지에서 내보낸 Backstage 기능을 어디에서 찾을 수 있는지 선언합니다. exports 필드와 유사하게 기능 내보내기 경로를 해당 기능 유형에 매핑한 것입니다.

backstage.features 필드 사용 예시

{  "name": "@backstage/plugin-catalog",  "backstage": {    "features": {      "./alpha": "@backstage/FrontendPlugin"    }  }}

이 필드는 패키지를 게시할 때 backstage-cli package prepack 명령이 자동으로 생성하므로 저장소에 커밋할 필요가 없습니다.

자체 도구로 패키지를 게시한다면 이 필드를 수동으로 채워야 합니다. 다음 기능 유형을 사용하세요.

@backstage/BackendFeature
@backstage/FrontendPlugin
@backstage/FrontendModule
@backstage/FrontendFeatureLoader

기능 유형에 대한 자세한 내용은 backend system 및 frontend system 문서를 참조하세요.

`backstage.pluginPackages`

플러그인의 일부인 모든 패키지에 대해 이 필드는 같은 플러그인에 직접 속한 모든 패키지 목록으로 설정되어야 합니다. 여기에는 프런트엔드 및 백엔드 플러그인 패키지와 관련 라이브러리가 포함되지만 모듈은 포함되지 않습니다.

이 필드는 backstage-cli repo fix --publish 명령으로 생성할 수 있습니다. 워크스페이스에서 같은 플러그인 ID를 가진 모든 패키지를 나열합니다.

backstage.pluginPackages 필드 사용 예시

{  "name": "@backstage/plugin-catalog",  "backstage": {    "role": "frontend-plugin",    "pluginId": "catalog",    "pluginPackages": [      "@backstage/plugin-catalog",      "@backstage/plugin-catalog-backend",      "@backstage/plugin-catalog-common",      "@backstage/plugin-catalog-node",      "@backstage/plugin-catalog-react"    ]  }  ...}

`backstage.pluginPackage`

플러그인의 모든 모듈 패키지에 대해 이 필드는 이 모듈이 대상으로 하는 플러그인 패키지의 이름으로 설정되어야 합니다.

이 필드는 backstage-cli repo fix --publish 명령으로 생성할 수 있습니다. 같은 워크스페이스에서 일치하는 플러그인 ID를 가진 패키지를 확인하지만 catalog, auth, scaffolder 같은 핵심 기능 플러그인 ID의 패키지 이름도 알고 있습니다. 패키지 이름을 추론할 수 없으면 수동으로 제공해야 합니다.

backstage.pluginPackage 필드 사용 예시

{  "name": "@backstage/plugin-catalog-backend-module-github",  "backstage": {    "role": "backend-plugin-module",    "pluginId": "catalog",    "pluginPackage": "@backstage/plugin-catalog-backend"  }  ...}

`backstage.peerModules`

플러그인 패키지의 경우 이 선택적 필드는 플러그인 간 통합을 위해 이 플러그인과 함께 설치해야 하는 모듈을 선언합니다. peer 모듈의 대상 플러그인이 Backstage 설치에 있다면 일반적으로 peer 모듈도 설치해야 합니다.

예를 들어 @backstage/plugin-scaffolder-backend를 사용한다면 scaffolder 엔터티 템플릿에 대한 카탈로그 지원을 활성화하기 위해 @backstage/plugin-catalog-backend-module-scaffolder-entity-model도 설치해야 합니다. scaffolder 플러그인은 peerModules를 통해 이 관계를 선언합니다.

이 필드는 특정 모듈을 정확히 대상으로 지정할 수 있도록 전체 패키지 이름을 사용합니다. 이 필드는 플러그인 패키지(backend-plugin 또는 frontend-plugin 역할)에만 사용할 수 있습니다.

backstage.peerModules 필드 사용 예시

{  "name": "@backstage/plugin-scaffolder-backend",  "backstage": {    "role": "backend-plugin",    "pluginId": "scaffolder",    "peerModules": [      "@backstage/plugin-catalog-backend-module-scaffolder-entity-model"    ]  }  ...}

플러그인은 여러 peer 모듈을 선언할 수 있습니다.

여러 peer 모듈 예시

{  "name": "@example/plugin-catalog-backend",  "backstage": {    "role": "backend-plugin",    "pluginId": "catalog",    "peerModules": [      "@example/plugin-search-backend-module-catalog",      "@example/plugin-explore-backend-module-catalog"    ]  }  ...}

`backstage.moved`

이 필드는 패키지가 이름이 변경되어 새 위치로 이동되었음을 나타냅니다. 이 필드는 Backstage CLI가 인식하며, 버전 올리기 명령이 자동으로 새 패키지를 사용하도록 전환합니다. 이 필드의 값은 새 패키지 이름이어야 합니다.

backstage.moved 필드 사용 예시

{  "name": "@backstage/plugin-azure-devops",  "backstage": {    "moved": "@backstage-community/plugin-azure-devops"  }  ...}

`backstage.inline`

true로 설정하면 이 필드는 모노레포 패키지가 비공개이며 의존성으로 처리되지 않고 종속 패키지에 인라인되어야 함을 나타냅니다. 이는 실질적으로 인라인된 패키지의 모든 가져온 코드가 패키지마다 한 번씩 소비 패키지에 복사된다는 뜻입니다.

이 플래그는 Backstage CLI 빌드 방식, @backstage/eslint-plugin이 패키지의 의존성을 린트하는 방식, @backstage/repo-tools가 처리하는 방식을 포함해 Backstage 도구의 여러 부분에 영향을 줍니다.

backstage.inline 필드는 주로 기본 Backstage 저장소에서 Backstage 핵심 프레임워크의 구현을 돕기 위한 것이지만, 다른 프로젝트에서도 사용할 수 있습니다.

이 플래그를 설정하려면 인라인 패키지는 게시해서는 안 되므로 최상위 private 필드도 설정해야 합니다.

backstage.moved 필드 사용 예시

{  "name": "@internal/utils",  "backstage": {    "inline": true  }  ...}

게시된 패키지의 메타데이터 (Metadata for Published Packages)

Backstage CLI의 도움으로 패키지를 게시할 때 패키지가 Backstage 생태계에 올바르게 설정되었는지 확인하기 위해 여러 메타데이터 검사가 수행됩니다. 이러한 검사는 게시를 위해 패키지를 준비하는 데 사용되는 backstage-cli package prepack 명령이 수행합니다. 이러한 검사는 모두 backstage-cli repo fix --publish 명령으로 별도로 검증할 수 있으며, 많은 경우 필수 메타데이터가 자동으로 생성될 수 있습니다. 따라서 Backstage 패키지를 게시하는 프로젝트에서는 fix 명령 실행을 워크플로의 일부로 만드는 것이 중요합니다.

이를 설정하려면 워크스페이스 루트 package.json에 다음 스크립트를 추가하는 것이 좋습니다.

{  "scripts": {    "fix": "backstage-cli repo fix --publish"  }}

이를 통해 저장소에서 작업하는 누구나 yarn fix를 실행해 워크스페이스의 모든 패키지를 확인하고 업데이트할 수 있습니다.

또한 보류 중인 수정 사항이 없는지 확인하는 검사를 CI 파이프라인에 추가해야 합니다. 이는 --check 플래그로 명령을 호출해 수행하며, GitHub actions에서는 다음과 같이 보일 것입니다.

- name: check for missing repo fixes  run: yarn fix --check

마지막으로 Husky나 다른 pre-commit 훅을 사용한다면 커밋 전에 fix 명령을 실행하는 훅을 설정할 수도 있습니다.

{  "lint-staged": {    "package.json": [      "yarn fix"    ]  }}

패키지 메타데이터