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 0ce25655a1..e817c989e7 100644 --- a/docs/tooling/package-metadata.md +++ b/docs/tooling/package-metadata.md @@ -168,6 +168,45 @@ The presence of this field is checked by the `backstage-cli package prepack` com } ``` +### `backstage.peerModules` + +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, 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 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.peerModules field" +{ + "name": "@backstage/plugin-scaffolder-backend", + "backstage": { + "role": "backend-plugin", + "pluginId": "scaffolder", + "peerModules": [ + "@backstage/plugin-catalog-backend-module-scaffolder-entity-model" + ] + } + ... +} +``` + +A plugin can declare multiple peer modules: + +```js title="Example of multiple peer modules" +{ + "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` 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. diff --git a/packages/cli-node/report.api.md b/packages/cli-node/report.api.md index 71f2b69ca8..55d2443643 100644 --- a/packages/cli-node/report.api.md +++ b/packages/cli-node/report.api.md @@ -25,6 +25,7 @@ export interface BackstagePackageJson { pluginId?: string | null; pluginPackage?: string; pluginPackages?: 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 a70720d23b..6d3da7cf82 100644 --- a/packages/cli-node/src/monorepo/PackageGraph.ts +++ b/packages/cli-node/src/monorepo/PackageGraph.ts @@ -91,6 +91,12 @@ export interface BackstagePackageJson { */ pluginPackages?: string[]; + /** + * 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. + */ + 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 c2c92a9770..6b31bed466 100644 --- a/packages/cli/src/modules/maintenance/commands/repo/fix.ts +++ b/packages/cli/src/modules/maintenance/commands/repo/fix.ts @@ -430,6 +430,47 @@ export function fixPluginPackages( } } +export function fixPeerModules(pkg: FixablePackage) { + const pkgBackstage = pkg.packageJson.backstage; + const role = pkgBackstage?.role; + if (!role) { + return; + } + + const peerModules = pkgBackstage.peerModules; + if (peerModules === undefined) { + return; + } + + const packagePath = relativePath( + paths.targetRoot, + resolvePath(pkg.dir, 'package.json'), + ); + + // Validate that peerModules is only used on plugin packages + if (role !== 'backend-plugin' && role !== 'frontend-plugin') { + throw new Error( + `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 peerModules is an array + if (!Array.isArray(peerModules)) { + throw new Error( + `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 peerModules) { + if (typeof entry !== 'string' || entry.length === 0) { + throw new Error( + `Invalid entry in 'backstage.peerModules' field in "${pkg.packageJson.name}", all entries must be non-empty package name strings in "${packagePath}"`, + ); + } + } +} + type PackageFixer = (pkg: FixablePackage, packages: FixablePackage[]) => void; export async function command(opts: OptionValues): Promise { @@ -444,6 +485,7 @@ export async function command(opts: OptionValues): Promise { fixRepositoryField, fixPluginId, fixPluginPackages, + fixPeerModules, // Run the publish preflight check too, to make sure we don't uncover errors during publishing publishPreflightCheck, ); 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/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/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": {