paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 28 Packages Projects Releases Wiki Activity

docs/package-metadata: document backstage fields

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2024-06-13 13:31:18 +02:00
parent 2e209638cc
commit 0fcdc412e4
1 changed files with 76 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tooling/package-metadata.md
+76
View File
@@ -77,3 +77,79 @@ The package scripts as defined by [NPM](https://docs.npmjs.com/cli/v10/configuri
### `configSchema`
The Backstage configuration schema for the package, as described by the [defining configuration](../conf/defining.md) section.
### `backstage`
This field is a collection of Backstage specific metadata fields. It is required for all Backstage packages, and any package that defines this field is considered to be part of the Backstage ecosystem. All sub-fields of this collection are defined below.
### `backstage.role`
This field defines the role of the package in the Backstage ecosystem. It can affect both the build process and runtime behavior, and signals the intended usage of the package to consumers. You can read more about this field in the [package roles](./cli/02-build-system.md#package-roles) section.
### `backstage.pluginId`
For any package that is part of a plugin, this field should be set to the plugin ID. This is the same ID as you would pass to the `createPlugin`, `createBackendPlugin`, or `createBackendModule` functions in the implementation of the package. It is also the same ID as the one described in the [name](#name) section.
This field can be generated by the `backstage-cli repo fix --publish` command. It will be inferred from the based on the package [name](#name) and [role](#backstagerole). If the package name is not actually part of a plugin but still has `plugin-*` in its name, you can set this field to be explicitly `null`.
The presence of this field is checked by the `backstage-cli package prepack` command, which is used to prepare a package for publishing.
### `backstage.pluginPackages`
For any package that is part of a plugin, this field should be set to a list of all packages that are directly part of the same plugin. This does not include module packages, only frontend and backend plugin packages as well as related libraries.
This field can be generated by the `backstage-cli repo fix --publish` command. It checks for and lists all packages with the same [plugin ID](#backstagepluginid) in the workspace.
The presence of this field is checked by the `backstage-cli package prepack` command, which is used to prepare a package for publishing.
```js title="Example"
{
"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`
For any module package of a plugin, this field should be set to the [name](#name) of the plugin package that this is a module for.
This field can be generated by the `backstage-cli repo fix --publish` command. It checks for packages with a matching [plugin ID](#backstagepluginid) in the same workspace, but also knows the package names of the core feature plugin IDs such as `'catalog'`, `'auth'`, `'scaffolder'`, etc. If the package name can not be inferred, it has to be provided manually.
The presence of this field is checked by the `backstage-cli package prepack` command, which is used to prepare a package for publishing.
```js title="Example"
{
"name": "@backstage/plugin-catalog-backend-module-github",
"backstage": {
"role": "backend-plugin-module",
"pluginId": "catalog",
"pluginPackage": "@backstage/plugin-catalog-backend"
}
...
}
```
### `backstage.moved`
This field indicates that a package has been renamed and moved to a new location. This field is recognized by the Backstage CLI, where the version bump command will automatically switch to using the new package instead. The value of this field should be the new package name.
```js title="Example"
{
"name": "@backstage/plugin-azure-devops",
"backstage": {
"moved": "@backstage-community/plugin-azure-devops"
}
...
}
```