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": {