From e6e5ae2a914d5687b629f91d276480d7974c4f49 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 12 Jun 2024 18:55:48 +0200 Subject: [PATCH 01/11] docs: intial package metadata docs Signed-off-by: Patrik Oldsberg --- docs/tooling/package-metadata.md | 13 +++++++++++++ microsite/sidebars.json | 3 ++- mkdocs.yml | 1 + 3 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 docs/tooling/package-metadata.md diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md new file mode 100644 index 0000000000..cbd0799ad3 --- /dev/null +++ b/docs/tooling/package-metadata.md @@ -0,0 +1,13 @@ +--- +id: package-metadata +title: Package Metadata +description: An inventory of well known package metadata fields in the Backstage ecosystem. +--- + +The `package.json` file is a JSON file that contains metadata about a JavaScript package, and in required for all package publish to NPM or a similar package registry. It is a [Node.js standard](https://nodejs.org/api/packages.html) that is expanded upon in the [NPM ecosystem](https://docs.npmjs.com/cli/v10/configuring-npm/package-json). + +## Known Metadata Fields + +This section documents the known `package.json` metadata fields that play a significant role in the Backstage ecosystem. + +All [fields defined by NPM](https://docs.npmjs.com/cli/v10/configuring-npm/package-json) are inherited by the Backstage ecosystem. The list below only includes those standard fields for which additional information is available. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 5ddd2f97f1..3ba9feeecd 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -362,7 +362,8 @@ "tooling/local-dev/linking-local-packages", "tooling/local-dev/debugging" ] - } + }, + "tooling/package-metadata" ], "Deployment": [ "deployment/index", diff --git a/mkdocs.yml b/mkdocs.yml index 026e76d531..110aa0933a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -180,6 +180,7 @@ nav: - Local Development: - Linking in Local Packages: 'tooling/local-dev/linking-local-packages.md' - Debugging Backstage: 'tooling/local-dev/debugging.md' + - Package Metadata: 'tooling/package-metadata.md' - Deployment: - Deploying Backstage: 'deployment/index.md' - Scaling: 'deployment/scaling.md' From 8638dd2323971cfbe3b7dfa510654a51d6084d7f Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 12 Jun 2024 18:59:51 +0200 Subject: [PATCH 02/11] docs/package-metadata: document name field Signed-off-by: Patrik Oldsberg --- docs/tooling/package-metadata.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index cbd0799ad3..3448b10c78 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -11,3 +11,25 @@ The `package.json` file is a JSON file that contains metadata about a JavaScript This section documents the known `package.json` metadata fields that play a significant role in the Backstage ecosystem. All [fields defined by NPM](https://docs.npmjs.com/cli/v10/configuring-npm/package-json) are inherited by the Backstage ecosystem. The list below only includes those standard fields for which additional information is available. + +### `name` + +The name of the package, as defined by [NPM](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#name). In addition, the following naming scheme is strongly encouraged for packages published in the Backstage ecosystem: + +First pick a package name prefix that is unique to your organization or collection of packages, but also places it within the Backstage ecosystem, for example: `@example/backstage`, `@example-backstage/`, or `example-backstage`. This prefix should be used by all packages that you publish, regardless of whether they're part of a plugin or not. + +Any package that is not part of a plugin should use the prefix along with a descriptive name, for example: `@example/backstage-components` or `@example/backstage-foo-client`. + +For plugin packages you should also pick a plugin ID and add `plugin-` to the prefix, along with a suffix based on the package role: + +- `-plugin-`: The main frontend code of the plugin. +- `-plugin--module-`: Optional modules related to the frontend plugin package. +- `-plugin--backend`: The main backend code of the plugin. +- `-plugin--backend-module-`: Optional modules related to the backend plugin package. +- `-plugin--react`: Shared widgets, hooks and similar that both the plugin itself and third-party frontend plugins or modules can depend on. +- `-plugin--node`: Utilities for backends that both the plugin backend itself and third-party backend plugins or modules can depend on. +- `-plugin--common`: An isomorphic package with platform agnostic models, clients, and utilities that all packages above or any third-party plugin or module can depend on. + +For example, a frontend package for the `poetry` plugin might be called `@example/backstage-plugin-poetry`, and a backend package for the same plugin might be called `@example/backstage-plugin-poetry-backend`. + +If you are creating a module for an existing package that is not part of your project, you should use the same prefix along with the plugin ID of the package that the module is for. For example, if you are creating a poetry provider module for `@backstage/plugin-catalog-backend`, you might call it `@example/backstage-plugin-catalog-backend-module-poetry-provider`. From ee8e016eeea3755a7955d5d06a8fc2559922a0fa Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 12 Jun 2024 19:13:40 +0200 Subject: [PATCH 03/11] docs/package-metadata: document repository field Signed-off-by: Patrik Oldsberg --- docs/tooling/package-metadata.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index 3448b10c78..673fe57edc 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -33,3 +33,7 @@ For plugin packages you should also pick a plugin ID and add `plugin-` For example, a frontend package for the `poetry` plugin might be called `@example/backstage-plugin-poetry`, and a backend package for the same plugin might be called `@example/backstage-plugin-poetry-backend`. If you are creating a module for an existing package that is not part of your project, you should use the same prefix along with the plugin ID of the package that the module is for. For example, if you are creating a poetry provider module for `@backstage/plugin-catalog-backend`, you might call it `@example/backstage-plugin-catalog-backend-module-poetry-provider`. + +### `repository` + +This field can be generated by the `backstage-cli repo fix --publish` command. The only requirement is that the `package.json` in your workspace root has the `repository` field documented. From 3ab55be3d8453f875e473b0e53a1bdb0b2efbd79 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 13 Jun 2024 11:05:01 +0200 Subject: [PATCH 04/11] docs/package-metadata: document entry point fields Signed-off-by: Patrik Oldsberg --- docs/tooling/package-metadata.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index 673fe57edc..e5bd2b55cf 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -37,3 +37,17 @@ If you are creating a module for an existing package that is not part of your pr ### `repository` This field can be generated by the `backstage-cli repo fix --publish` command. The only requirement is that the `package.json` in your workspace root has the `repository` field documented. + +### `main` + +The main entry point of the package, pointing to the source file for development. This field along with other entry point fields such as `module` and `types` are rewritten when packaging the package for distribution. You can read more about this process in the [publishing](./cli/02-build-system.md#publishing) section, and it is also used for [backend production builds](./cli/02-build-system.md#backend-production). + +### `exports` + +The exports of the package, as defined by [Node.js](https://nodejs.org/api/packages.html#exports). This field is used to define the entry points of the package. As with other entry point fields, the exports should point to source files for development. They will the be rewritten when packaging the package for distribution. You can read more about this in the [sub-path exports](./cli/02-build-system.md#subpath-exports) section. + +### `typeVersions` + +This field is used to specify the type entry points for the package, the TypeScript equivalent of the `exports` field. TypeScript also supports defining this in the `exports` field, but that requires that the `moduleResolution` option in `tsconfig.json` is set to `node16` or `bundler`, which we currently do not support. + +This field can be generated by the `backstage-cli repo fix` command. First fill out the `exports` field to point to source fields, which will then be used to generate the `typeVersions`. From 013449b98a29f6e5a5953a80e0f24c64c01efa35 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 13 Jun 2024 11:51:24 +0200 Subject: [PATCH 05/11] docs/package-metadata: document sideEffects field Signed-off-by: Patrik Oldsberg --- docs/tooling/package-metadata.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index e5bd2b55cf..f3ffe6986e 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -51,3 +51,9 @@ The exports of the package, as defined by [Node.js](https://nodejs.org/api/packa This field is used to specify the type entry points for the package, the TypeScript equivalent of the `exports` field. TypeScript also supports defining this in the `exports` field, but that requires that the `moduleResolution` option in `tsconfig.json` is set to `node16` or `bundler`, which we currently do not support. This field can be generated by the `backstage-cli repo fix` command. First fill out the `exports` field to point to source fields, which will then be used to generate the `typeVersions`. + +### `sideEffects` + +This field declares whether it is safe to remove unused code when bundling this package into a frontend build, and is defined for example by [WebPack](https://github.com/backstage/backstage/blob/8d5cdb5d536cc8eb444da4b57dca4e36716f4535/plugins/auth-backend-module-google-provider/config.d.ts#L22). + +This field can be generated by the `backstage-cli repo fix` command. It will set to `false` by default for all frontend packages, since Backstage frontend packages should generally never have any side effects. If your package does have side effects, you can set explicitly set this field to `true`. From e5ce39fcdcacc7da21ce9276bdd7f82c6d2c6b9d Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 13 Jun 2024 11:57:49 +0200 Subject: [PATCH 06/11] docs/package-metadata: document scripts field Signed-off-by: Patrik Oldsberg --- docs/tooling/package-metadata.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index f3ffe6986e..7dc583bfda 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -57,3 +57,19 @@ This field can be generated by the `backstage-cli repo fix` command. First fill This field declares whether it is safe to remove unused code when bundling this package into a frontend build, and is defined for example by [WebPack](https://github.com/backstage/backstage/blob/8d5cdb5d536cc8eb444da4b57dca4e36716f4535/plugins/auth-backend-module-google-provider/config.d.ts#L22). This field can be generated by the `backstage-cli repo fix` command. It will set to `false` by default for all frontend packages, since Backstage frontend packages should generally never have any side effects. If your package does have side effects, you can set explicitly set this field to `true`. + +### `scripts` + +The package scripts as defined by [NPM](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#scripts). The Backstage CLI provides a set of standard scripts, which you can read more about in the [build system](./cli/02-build-system.md) section. The full list of scripts is as follows: + +```js +"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" +} +``` From 2e209638cc4e18737ffb6e1e58b26d7210260eba Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 13 Jun 2024 12:03:12 +0200 Subject: [PATCH 07/11] docs/package-metadata: document configSchema field Signed-off-by: Patrik Oldsberg --- docs/tooling/package-metadata.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index 7dc583bfda..31a77b7469 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -73,3 +73,7 @@ The package scripts as defined by [NPM](https://docs.npmjs.com/cli/v10/configuri "postpack": "backstage-cli package postpack" } ``` + +### `configSchema` + +The Backstage configuration schema for the package, as described by the [defining configuration](../conf/defining.md) section. From 0fcdc412e46ae86fb6acfb15ebd23dc32b5b3eda Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 13 Jun 2024 13:31:18 +0200 Subject: [PATCH 08/11] docs/package-metadata: document backstage fields Signed-off-by: Patrik Oldsberg --- docs/tooling/package-metadata.md | 76 ++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index 31a77b7469..9497065a52 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -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" + } + ... +} +``` From 0a898945e94241b119332bb773df2b57007fa6d0 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 13 Jun 2024 15:24:17 +0200 Subject: [PATCH 09/11] docs/package-metadata: add section about metadata for published packages Signed-off-by: Patrik Oldsberg --- docs/tooling/cli/02-build-system.md | 5 ++++- docs/tooling/package-metadata.md | 35 +++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/tooling/cli/02-build-system.md b/docs/tooling/cli/02-build-system.md index bfdb21f45f..1bcf7ad30c 100644 --- a/docs/tooling/cli/02-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -617,7 +617,10 @@ A complete launch configuration for VS Code debugging may look like this: Package publishing is an optional part of the Backstage build system and not something you will need to worry about unless you are publishing packages to a -registry. In order to publish a package, you first need to build it, which will +registry. In addition to the documentation in the section, be sure to also read +the section on [metadata for published packages](../package-metadata.md#metadata-for-published-packages). + +In order to publish a package, you first need to build it, which will populate the `dist` folder. Because the Backstage build system is optimized for local development along with our particular TypeScript and bundling setup, it is not possible to publish the package immediately at this point. This is because diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index 9497065a52..ce64c9f1c2 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -153,3 +153,38 @@ This field indicates that a package has been renamed and moved to a new location ... } ``` + +## Metadata for Published Packages + +When publishing a package with the help of the Backstage CLI, there are a number of metadata checks that are performed to ensure that the package is correctly set up for the Backstage ecosystem. These checks are performed by the `backstage-cli package prepack` command, which is used to prepare a package for publishing. These checks can all also be verified separately using the `backstage-cli repo fix --publish` command, and in many cases the required metadata can be generated automatically. It is therefore important to make running the `fix` command part of your workflow in any project that is publishing Backstage packages. + +To set this up, we recommend that you add the following script to the root `package.json` of your workspace: + +```js +{ + "scripts": { + "fix": "backstage-cli repo fix --publish" + } +} +``` + +This allows anyone working in the repo to run `yarn fix` to check and update all packages in the workspace. + +In addition, you should also add a check to your CI pipeline that ensures that there are no pending fixes. This is done by calling the command with the `--check` flag, which in GitHub actions would look something like this: + +```yaml +- name: check for missing repo fixes + run: yarn fix --check +``` + +Finally, if you are using Husky or any other pre-commit hook, you can also set up a hook to run the fix command before committing: + +```js +{ + "lint-staged": { + "package.json": [ + "yarn fix" + ] + } +} +``` From f29347f1d74fed65ec8d319178f99970845d7fe7 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 13 Jun 2024 15:57:52 +0200 Subject: [PATCH 10/11] docs/package-metadata: text fixes Signed-off-by: Patrik Oldsberg --- docs/tooling/package-metadata.md | 36 +++++++++++++++++--------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index ce64c9f1c2..63ce6d1085 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -4,7 +4,7 @@ title: Package Metadata description: An inventory of well known package metadata fields in the Backstage ecosystem. --- -The `package.json` file is a JSON file that contains metadata about a JavaScript package, and in required for all package publish to NPM or a similar package registry. It is a [Node.js standard](https://nodejs.org/api/packages.html) that is expanded upon in the [NPM ecosystem](https://docs.npmjs.com/cli/v10/configuring-npm/package-json). +The `package.json` file is a JSON file that contains metadata about a JavaScript package. It is a [Node.js standard](https://nodejs.org/api/packages.html) that is expanded upon in the [NPM ecosystem](https://docs.npmjs.com/cli/v10/configuring-npm/package-json), and is required for all packages published to NPM or a similar package registry. ## Known Metadata Fields @@ -36,25 +36,27 @@ If you are creating a module for an existing package that is not part of your pr ### `repository` +The location of the source code for the package, as defined by [NPM](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#repository). + This field can be generated by the `backstage-cli repo fix --publish` command. The only requirement is that the `package.json` in your workspace root has the `repository` field documented. ### `main` -The main entry point of the package, pointing to the source file for development. This field along with other entry point fields such as `module` and `types` are rewritten when packaging the package for distribution. You can read more about this process in the [publishing](./cli/02-build-system.md#publishing) section, and it is also used for [backend production builds](./cli/02-build-system.md#backend-production). +The main entry point of the package, as defined by [NPM](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#main). In a standard Backstage setup this should point to the entry point for local development, typically `src/index.ts`. This field along with other entry point fields such as `module` and `types` are rewritten when packaging the package for distribution. You can read more about this process in the [publishing](./cli/02-build-system.md#publishing) section, and it is also used for [backend production builds](./cli/02-build-system.md#backend-production). ### `exports` -The exports of the package, as defined by [Node.js](https://nodejs.org/api/packages.html#exports). This field is used to define the entry points of the package. As with other entry point fields, the exports should point to source files for development. They will the be rewritten when packaging the package for distribution. You can read more about this in the [sub-path exports](./cli/02-build-system.md#subpath-exports) section. +The exports of the package, as defined by [Node.js](https://nodejs.org/api/packages.html#exports). This field is used to define the entry points of the package. As with other entry point fields, the exports should point to entry points for local development. They will the be rewritten when packaging the package for distribution. You can read more about this in the [sub-path exports](./cli/02-build-system.md#subpath-exports) section. ### `typeVersions` -This field is used to specify the type entry points for the package, the TypeScript equivalent of the `exports` field. TypeScript also supports defining this in the `exports` field, but that requires that the `moduleResolution` option in `tsconfig.json` is set to `node16` or `bundler`, which we currently do not support. +This field is used to specify versioned type entry points for the package, as defined by [TypeScript](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html#version-selection-with-typesversions), and is used as the equivalent of the `exports` field. TypeScript does support type declarations in the `exports` field, but that requires that the `moduleResolution` option in `tsconfig.json` is set to `node16` or `bundler`, which the Backstage ecosystem currently does not support. -This field can be generated by the `backstage-cli repo fix` command. First fill out the `exports` field to point to source fields, which will then be used to generate the `typeVersions`. +This field can be generated by the `backstage-cli repo fix` command. First fill out the `exports` field to point to source fields, which will then be used to generate `typeVersions`. ### `sideEffects` -This field declares whether it is safe to remove unused code when bundling this package into a frontend build, and is defined for example by [WebPack](https://github.com/backstage/backstage/blob/8d5cdb5d536cc8eb444da4b57dca4e36716f4535/plugins/auth-backend-module-google-provider/config.d.ts#L22). +This field declares whether it is safe to remove unused code through tree shaking when bundling this package into a frontend build, and is defined for example by [WebPack](https://github.com/backstage/backstage/blob/8d5cdb5d536cc8eb444da4b57dca4e36716f4535/plugins/auth-backend-module-google-provider/config.d.ts#L22). This field can be generated by the `backstage-cli repo fix` command. It will set to `false` by default for all frontend packages, since Backstage frontend packages should generally never have any side effects. If your package does have side effects, you can set explicitly set this field to `true`. @@ -76,7 +78,7 @@ 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. +The Backstage configuration schema for the package, as described in the [defining configuration](../conf/defining.md) section. ### `backstage` @@ -90,19 +92,19 @@ This field defines the role of the package in the Backstage ecosystem. It can af 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`. +This field can be generated by the `backstage-cli repo fix --publish` command. The plugin ID will be inferred from 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. +The presence of this field is checked by the `backstage-cli package prepack` command, which is used to prepare a package for publishing. You can read more about this requirement in the section on [metadata for published packages](#metadata-for-published-packages). ### `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. +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 includes frontend and backend plugin packages as well as related libraries, but not modules. -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. +This field can be generated by the `backstage-cli repo fix --publish` command. It will list 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. +The presence of this field is checked by the `backstage-cli package prepack` command, which is used to prepare a package for publishing. You can read more about this requirement in the section on [metadata for published packages](#metadata-for-published-packages). -```js title="Example" +```js title="Example usage of the backstage.pluginPackages field" { "name": "@backstage/plugin-catalog", "backstage": { @@ -124,11 +126,11 @@ The presence of this field is checked by the `backstage-cli package prepack` com 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. +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. +The presence of this field is checked by the `backstage-cli package prepack` command, which is used to prepare a package for publishing. You can read more about this requirement in the section on [metadata for published packages](#metadata-for-published-packages). -```js title="Example" +```js title="Example usage of the backstage.pluginPackage field" { "name": "@backstage/plugin-catalog-backend-module-github", "backstage": { @@ -144,7 +146,7 @@ The presence of this field is checked by the `backstage-cli package prepack` com 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" +```js title="Example usage of the backstage.moved field" { "name": "@backstage/plugin-azure-devops", "backstage": { From 99e061c735601b0c3aec4a93cf1d8c300b9fa5af Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 13 Jun 2024 15:59:02 +0200 Subject: [PATCH 11/11] beps/0009: add reference to the new package metadata section in docs Signed-off-by: Patrik Oldsberg --- beps/0009-plugin-metadata/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beps/0009-plugin-metadata/README.md b/beps/0009-plugin-metadata/README.md index 79d7dc2172..c0ae487daa 100644 --- a/beps/0009-plugin-metadata/README.md +++ b/beps/0009-plugin-metadata/README.md @@ -85,7 +85,7 @@ To the furthest extent possible we will rely on established standards for `packa In the case of new fields we always define them to be part of the top-level `"backstage"` field. The assumption is that any field that we define will always be tied to the Backstage ecosystem, even in the case of general fields such as "lifecycle". The only exception to this is if we believe that a field is generic enough that it could genuinely become part of the broader NPM ecosystem. -All fields must be documented in a new section of the "Tooling" documentation on backstage.io. This documentation should include a description of the field, what it is used for, and what the expected values are. The documentation must also mention whether the field is expected to be filled in manually, or if it will be generated by tooling. Changes to this documentation must be approved by the Backstage core maintainers, it is not owned by individual project area maintainers. +All fields must be documented in a [new section](../../docs/tooling/package-metadata.md) of the "Tooling" documentation on backstage.io. This documentation should include a description of the field, what it is used for, and what the expected values are. The documentation must also mention whether the field is expected to be filled in manually, or if it will be generated by tooling. Changes to this documentation must be approved by the Backstage core maintainers, it is not owned by individual project area maintainers. ### Package Relationships