diff --git a/.changeset/integration-for-metadata.md b/.changeset/integration-for-metadata.md deleted file mode 100644 index 91cd6b67b5..0000000000 --- a/.changeset/integration-for-metadata.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -'@backstage/cli': patch -'@backstage/cli-node': patch -'@backstage/plugin-catalog-backend-module-scaffolder-entity-model': patch -'@backstage/plugin-search-backend-module-catalog': patch -'@backstage/plugin-search-backend-module-techdocs': patch -'@backstage/plugin-scaffolder-backend-module-notifications': patch ---- - -Added support for the new `integrationFor` metadata field in `package.json`. This field enables cross-plugin module discovery by declaring which packages a module provides integration for. Tooling and documentation systems can use this metadata to surface relevant integrations and help users discover modules that work together. diff --git a/.changeset/peer-modules-cli-support.md b/.changeset/peer-modules-cli-support.md new file mode 100644 index 0000000000..cfe8631995 --- /dev/null +++ b/.changeset/peer-modules-cli-support.md @@ -0,0 +1,6 @@ +--- +'@backstage/cli': patch +'@backstage/cli-node': patch +--- + +Added support for the new `peerModules` metadata field in `package.json`. This field allows plugin packages to declare modules that should be installed alongside them for cross-plugin integrations. The field is validated by `backstage-cli repo fix --publish`. diff --git a/.changeset/peer-modules-plugin-metadata.md b/.changeset/peer-modules-plugin-metadata.md new file mode 100644 index 0000000000..dde81c84be --- /dev/null +++ b/.changeset/peer-modules-plugin-metadata.md @@ -0,0 +1,8 @@ +--- +'@backstage/plugin-scaffolder-backend': patch +'@backstage/plugin-notifications-backend': patch +'@backstage/plugin-catalog-backend': patch +'@backstage/plugin-techdocs-backend': patch +--- + +Added `peerModules` metadata declaring recommended modules for cross-plugin integrations. diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md index 8f489f753c..e817c989e7 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -168,39 +168,39 @@ The presence of this field is checked by the `backstage-cli package prepack` com } ``` -### `backstage.integrationFor` +### `backstage.peerModules` -For any module package, this optional field can be set to an array of package names that this module provides integration for. This field enables cross-plugin module discovery by declaring relationships between modules and the plugins they enhance or integrate with. +For plugin packages, this optional field declares modules that should be installed alongside this plugin for cross-plugin integrations. If the peer module's target plugin is present in the Backstage installation, you should typically have the peer module installed as well. -For example, a Catalog module that provides Scaffolder-related entity processing can declare that it integrates with the Scaffolder backend. Tooling and documentation systems can use this metadata to surface relevant integrations and help users discover modules that work together. +For example, if you use `@backstage/plugin-scaffolder-backend`, you should also install `@backstage/plugin-catalog-backend-module-scaffolder-entity-model` to enable catalog support for scaffolder entity templates. The scaffolder plugin declares this relationship through `peerModules`. -The field uses full package names rather than plugin IDs to allow precise targeting of specific packages. When referencing packages it is preferred to use a matching role, i.e. a `backend-plugin-module` referencing a `backend-plugin` package, but it is not required, in fact any of the packages in the target plugin's `pluginPackages` field can be used. +The field uses full package names to allow precise targeting of specific modules. This field can only be used on plugin packages (`backend-plugin` or `frontend-plugin` roles). -```js title="Example usage of the backstage.integrationFor field" +```js title="Example usage of the backstage.peerModules field" { - "name": "@backstage/plugin-catalog-backend-module-scaffolder", + "name": "@backstage/plugin-scaffolder-backend", "backstage": { - "role": "backend-plugin-module", - "pluginId": "catalog", - "pluginPackage": "@backstage/plugin-catalog-backend", - "integrationFor": ["@backstage/plugin-scaffolder-backend"] + "role": "backend-plugin", + "pluginId": "scaffolder", + "peerModules": [ + "@backstage/plugin-catalog-backend-module-scaffolder-entity-model" + ] } ... } ``` -A module can declare integration with multiple packages: +A plugin can declare multiple peer modules: -```js title="Example of multi-plugin integration" +```js title="Example of multiple peer modules" { - "name": "@example/plugin-catalog-backend-module-ci-status", + "name": "@example/plugin-catalog-backend", "backstage": { - "role": "backend-plugin-module", + "role": "backend-plugin", "pluginId": "catalog", - "pluginPackage": "@backstage/plugin-catalog-backend", - "integrationFor": [ - "@backstage-community/plugin-jenkins-backend", - "@backstage-community/plugin-github-actions-backend" + "peerModules": [ + "@example/plugin-search-backend-module-catalog", + "@example/plugin-explore-backend-module-catalog" ] } ... diff --git a/packages/cli-node/report.api.md b/packages/cli-node/report.api.md index c427d57216..55d2443643 100644 --- a/packages/cli-node/report.api.md +++ b/packages/cli-node/report.api.md @@ -25,7 +25,7 @@ export interface BackstagePackageJson { pluginId?: string | null; pluginPackage?: string; pluginPackages?: string[]; - integrationFor?: string[]; + peerModules?: string[]; features?: Record; }; // (undocumented) diff --git a/packages/cli-node/src/monorepo/PackageGraph.ts b/packages/cli-node/src/monorepo/PackageGraph.ts index fcd3f4d97d..6d3da7cf82 100644 --- a/packages/cli-node/src/monorepo/PackageGraph.ts +++ b/packages/cli-node/src/monorepo/PackageGraph.ts @@ -92,9 +92,10 @@ export interface BackstagePackageJson { pluginPackages?: string[]; /** - * Package names that this module provides integration for. When any of these packages are used, this module should be suggested as a related integration. + * Module packages that should be installed alongside this plugin for cross-plugin integrations. + * If the peer module's target plugin is present, you should have the peer module installed. */ - integrationFor?: string[]; + peerModules?: string[]; /** * The feature types exported from the package, indexed by path. diff --git a/packages/cli/src/modules/maintenance/commands/repo/fix.ts b/packages/cli/src/modules/maintenance/commands/repo/fix.ts index ad5793a9c3..6b31bed466 100644 --- a/packages/cli/src/modules/maintenance/commands/repo/fix.ts +++ b/packages/cli/src/modules/maintenance/commands/repo/fix.ts @@ -430,15 +430,15 @@ export function fixPluginPackages( } } -export function fixIntegrationFor(pkg: FixablePackage) { +export function fixPeerModules(pkg: FixablePackage) { const pkgBackstage = pkg.packageJson.backstage; const role = pkgBackstage?.role; if (!role) { return; } - const integrationFor = pkgBackstage.integrationFor; - if (integrationFor === undefined) { + const peerModules = pkgBackstage.peerModules; + if (peerModules === undefined) { return; } @@ -447,25 +447,25 @@ export function fixIntegrationFor(pkg: FixablePackage) { resolvePath(pkg.dir, 'package.json'), ); - // Validate that integrationFor is only used on module packages - if (role !== 'backend-plugin-module' && role !== 'frontend-plugin-module') { + // Validate that peerModules is only used on plugin packages + if (role !== 'backend-plugin' && role !== 'frontend-plugin') { throw new Error( - `The 'backstage.integrationFor' field in "${pkg.packageJson.name}" can only be used on module packages (backend-plugin-module or frontend-plugin-module), but package has role '${role}' in "${packagePath}"`, + `The 'backstage.peerModules' field in "${pkg.packageJson.name}" can only be used on plugin packages (backend-plugin or frontend-plugin), but package has role '${role}' in "${packagePath}"`, ); } - // Validate that integrationFor is an array - if (!Array.isArray(integrationFor)) { + // Validate that peerModules is an array + if (!Array.isArray(peerModules)) { throw new Error( - `Invalid 'backstage.integrationFor' field in "${pkg.packageJson.name}", must be an array of package names in "${packagePath}"`, + `Invalid 'backstage.peerModules' field in "${pkg.packageJson.name}", must be an array of package names in "${packagePath}"`, ); } // Validate that all entries are non-empty strings - for (const entry of integrationFor) { + for (const entry of peerModules) { if (typeof entry !== 'string' || entry.length === 0) { throw new Error( - `Invalid entry in 'backstage.integrationFor' field in "${pkg.packageJson.name}", all entries must be non-empty package name strings in "${packagePath}"`, + `Invalid entry in 'backstage.peerModules' field in "${pkg.packageJson.name}", all entries must be non-empty package name strings in "${packagePath}"`, ); } } @@ -485,7 +485,7 @@ export async function command(opts: OptionValues): Promise { fixRepositoryField, fixPluginId, fixPluginPackages, - fixIntegrationFor, + fixPeerModules, // Run the publish preflight check too, to make sure we don't uncover errors during publishing publishPreflightCheck, ); diff --git a/plugins/catalog-backend-module-scaffolder-entity-model/package.json b/plugins/catalog-backend-module-scaffolder-entity-model/package.json index 831ea73185..77afbcf307 100644 --- a/plugins/catalog-backend-module-scaffolder-entity-model/package.json +++ b/plugins/catalog-backend-module-scaffolder-entity-model/package.json @@ -5,10 +5,7 @@ "backstage": { "role": "backend-plugin-module", "pluginId": "catalog", - "pluginPackage": "@backstage/plugin-catalog-backend", - "integrationFor": [ - "@backstage/plugin-scaffolder-backend" - ] + "pluginPackage": "@backstage/plugin-catalog-backend" }, "publishConfig": { "access": "public" diff --git a/plugins/catalog-backend/package.json b/plugins/catalog-backend/package.json index f19349c4b0..72e2798552 100644 --- a/plugins/catalog-backend/package.json +++ b/plugins/catalog-backend/package.json @@ -11,6 +11,9 @@ "@backstage/plugin-catalog-common", "@backstage/plugin-catalog-node", "@backstage/plugin-catalog-react" + ], + "peerModules": [ + "@backstage/plugin-search-backend-module-catalog" ] }, "publishConfig": { diff --git a/plugins/notifications-backend/package.json b/plugins/notifications-backend/package.json index f7e1c8c219..5a1209cc9e 100644 --- a/plugins/notifications-backend/package.json +++ b/plugins/notifications-backend/package.json @@ -9,6 +9,9 @@ "@backstage/plugin-notifications-backend", "@backstage/plugin-notifications-common", "@backstage/plugin-notifications-node" + ], + "peerModules": [ + "@backstage/plugin-scaffolder-backend-module-notifications" ] }, "publishConfig": { diff --git a/plugins/scaffolder-backend-module-notifications/package.json b/plugins/scaffolder-backend-module-notifications/package.json index 92c66d5a97..f56864d918 100644 --- a/plugins/scaffolder-backend-module-notifications/package.json +++ b/plugins/scaffolder-backend-module-notifications/package.json @@ -5,10 +5,7 @@ "backstage": { "role": "backend-plugin-module", "pluginId": "scaffolder", - "pluginPackage": "@backstage/plugin-scaffolder-backend", - "integrationFor": [ - "@backstage/plugin-notifications-backend" - ] + "pluginPackage": "@backstage/plugin-scaffolder-backend" }, "publishConfig": { "access": "public", diff --git a/plugins/scaffolder-backend/package.json b/plugins/scaffolder-backend/package.json index 0040cc81d3..7a2356f688 100644 --- a/plugins/scaffolder-backend/package.json +++ b/plugins/scaffolder-backend/package.json @@ -12,6 +12,9 @@ "@backstage/plugin-scaffolder-node", "@backstage/plugin-scaffolder-node-test-utils", "@backstage/plugin-scaffolder-react" + ], + "peerModules": [ + "@backstage/plugin-catalog-backend-module-scaffolder-entity-model" ] }, "publishConfig": { diff --git a/plugins/search-backend-module-catalog/package.json b/plugins/search-backend-module-catalog/package.json index 2626f31839..b83fbd72ac 100644 --- a/plugins/search-backend-module-catalog/package.json +++ b/plugins/search-backend-module-catalog/package.json @@ -5,10 +5,7 @@ "backstage": { "role": "backend-plugin-module", "pluginId": "search", - "pluginPackage": "@backstage/plugin-search-backend", - "integrationFor": [ - "@backstage/plugin-catalog-backend" - ] + "pluginPackage": "@backstage/plugin-search-backend" }, "publishConfig": { "access": "public", diff --git a/plugins/search-backend-module-techdocs/package.json b/plugins/search-backend-module-techdocs/package.json index 68bc4317a9..d7ecbf641c 100644 --- a/plugins/search-backend-module-techdocs/package.json +++ b/plugins/search-backend-module-techdocs/package.json @@ -5,10 +5,7 @@ "backstage": { "role": "backend-plugin-module", "pluginId": "search", - "pluginPackage": "@backstage/plugin-search-backend", - "integrationFor": [ - "@backstage/plugin-techdocs-backend" - ] + "pluginPackage": "@backstage/plugin-search-backend" }, "publishConfig": { "access": "public" diff --git a/plugins/techdocs-backend/package.json b/plugins/techdocs-backend/package.json index eda723627b..e49e61a6a3 100644 --- a/plugins/techdocs-backend/package.json +++ b/plugins/techdocs-backend/package.json @@ -11,6 +11,9 @@ "@backstage/plugin-techdocs-common", "@backstage/plugin-techdocs-node", "@backstage/plugin-techdocs-react" + ], + "peerModules": [ + "@backstage/plugin-search-backend-module-techdocs" ] }, "publishConfig": {