diff --git a/.changeset/rare-hotels-cough.md b/.changeset/rare-hotels-cough.md new file mode 100644 index 0000000000..1a2395cf56 --- /dev/null +++ b/.changeset/rare-hotels-cough.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-plugin-api': patch +--- + +Added documentation for `createBackendModule`, with guidelines for choosing a module ID. diff --git a/.changeset/young-bugs-remember.md b/.changeset/young-bugs-remember.md new file mode 100644 index 0000000000..8f78495ed7 --- /dev/null +++ b/.changeset/young-bugs-remember.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-catalog-backend-module-github': patch +'@backstage/plugin-scaffolder-backend': patch +--- + +Updated the `moduleId` of the experimental module export. diff --git a/packages/backend-plugin-api/api-report.md b/packages/backend-plugin-api/api-report.md index 2d4e431502..70ab168053 100644 --- a/packages/backend-plugin-api/api-report.md +++ b/packages/backend-plugin-api/api-report.md @@ -71,7 +71,7 @@ export const cacheServiceRef: ServiceRef; // @public (undocumented) export const configServiceRef: ServiceRef; -// @public (undocumented) +// @public export function createBackendModule< TOptions extends object | undefined = undefined, >( diff --git a/packages/backend-plugin-api/src/wiring/factories.ts b/packages/backend-plugin-api/src/wiring/factories.ts index 35f1ad1b7c..831e40f9f8 100644 --- a/packages/backend-plugin-api/src/wiring/factories.ts +++ b/packages/backend-plugin-api/src/wiring/factories.ts @@ -69,7 +69,18 @@ export interface BackendModuleConfig { ): void; } -/** @public */ +/** + * @public + * + * Creates a new backend module for a given plugin. + * + * The `moduleId` should be equal to the module-specific prefix of the exported name, such + * that the full name is `moduleId + PluginId + "Module"`. For example, a GitHub entity + * provider module for the `catalog` plugin might have the module ID `'githubEntityProvider'`, + * and the full exported name would be `githubEntityProviderCatalogModule`. + * + * The `pluginId` should exactly match the `id` of the plugin that the module extends. + */ export function createBackendModule< TOptions extends object | undefined = undefined, >( diff --git a/plugins/catalog-backend-module-github/src/module.ts b/plugins/catalog-backend-module-github/src/module.ts index 4eccef0611..0391855618 100644 --- a/plugins/catalog-backend-module-github/src/module.ts +++ b/plugins/catalog-backend-module-github/src/module.ts @@ -41,7 +41,7 @@ export type GithubEntityProviderCatalogModuleOptions = { */ export const githubEntityProviderCatalogModule = createBackendModule({ pluginId: 'catalog', - moduleId: 'github-entity-provider', + moduleId: 'githubEntityProvider', register(env, options?: GithubEntityProviderCatalogModuleOptions) { env.registerInit({ deps: { diff --git a/plugins/catalog-node/src/catalogService.test.ts b/plugins/catalog-node/src/catalogService.test.ts index 5599218988..9ecf08b30e 100644 --- a/plugins/catalog-node/src/catalogService.test.ts +++ b/plugins/catalog-node/src/catalogService.test.ts @@ -37,7 +37,7 @@ describe('catalogServiceRef', () => { }); const testModule = createBackendModule({ - moduleId: 'test.module', + moduleId: 'test', pluginId: 'test', register(env) { env.registerInit({ diff --git a/plugins/scaffolder-backend/src/extension/ScaffolderCatalogModule.ts b/plugins/scaffolder-backend/src/extension/ScaffolderCatalogModule.ts index 0fb3c2e428..4e9b6f75c9 100644 --- a/plugins/scaffolder-backend/src/extension/ScaffolderCatalogModule.ts +++ b/plugins/scaffolder-backend/src/extension/ScaffolderCatalogModule.ts @@ -22,7 +22,7 @@ import { ScaffolderEntitiesProcessor } from '../processor'; * Registers the ScaffolderEntitiesProcessor with the catalog processing extension point. */ export const scaffolderCatalogModule = createBackendModule({ - moduleId: 'scaffolder.module', + moduleId: 'scaffolder', pluginId: 'catalog', register(env) { env.registerInit({