From 31f6f90b260e8fec7a6fa3bbef773c6a53a080ba Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 14 Nov 2023 15:43:52 +0100 Subject: [PATCH] docs/backend-system: update docs to be clearer about module extension points Signed-off-by: Patrik Oldsberg --- .../architecture/05-extension-points.md | 2 +- .../building-plugins-and-modules/01-index.md | 11 +++++++---- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/backend-system/architecture/05-extension-points.md b/docs/backend-system/architecture/05-extension-points.md index d8d993b5bf..e6eb0a9e16 100644 --- a/docs/backend-system/architecture/05-extension-points.md +++ b/docs/backend-system/architecture/05-extension-points.md @@ -70,7 +70,7 @@ Note that we create a closure that adds to a shared `actions` structure when `ad ## Module Extension Points -Just like plugins, modules can also provide their own extension points. The API for registering and using extension points is the same as for plugins. However, modules should typically only use extension points to allow for complex internal customizations by users of the plugin module. It is therefore preferred to export the extension point directly from the module package, rather than creating a separate node library for that purpose. +Just like plugins, modules can also provide their own extension points. The API for registering and using extension points is the same as for plugins. However, modules should typically only use extension points to allow for complex internal customizations by users of the plugin module. It is therefore preferred to export the extension point directly from the module package, rather than creating a separate node library for that purpose. Extension points exported by a module are used the same way as extension points exported by a plugin, you create your own separate module and declare a dependency on the extension point that you want to interact with. ## Extension Point Design diff --git a/docs/backend-system/building-plugins-and-modules/01-index.md b/docs/backend-system/building-plugins-and-modules/01-index.md index fed074b258..7d97694aec 100644 --- a/docs/backend-system/building-plugins-and-modules/01-index.md +++ b/docs/backend-system/building-plugins-and-modules/01-index.md @@ -72,12 +72,12 @@ items. ## Modules -Backend modules are used to extend [plugins](../architecture/04-plugins.md) with +Backend modules are used to extend [plugins](../architecture/04-plugins.md) or other modules with additional features or change existing behavior. They must always be installed -in the same backend instance as the plugin that they extend, and may only extend -a single plugin. Modules interact with their target plugin using the [extension +in the same backend instance as the plugin or module that they extend, and may only extend a single plugin and modules from that plugin at a time. +Modules interact with their target plugin or module using the [extension points](../architecture/05-extension-points.md) registered by the plugin, while also being -able to depend on the [services](../architecture/03-services.md) of that plugin. +able to depend on the [services](../architecture/03-services.md) of the target plugin. That last point is worth reiterating: injected `plugin` scoped services will be the exact same ones as the target plugin will receive later, i.e. they will be scoped @@ -88,6 +88,9 @@ package, for example `@backstage/plugin-catalog-node`, and does not directly declare a dependency on the plugin package itself. This is to avoid a direct dependency and potentially cause duplicate installations of the plugin package, while duplicate installations of library packages should always be supported. +Modules with extension points typically export their extension points from the same +package however, since the extension points are generally only intended for internal +customizations where package versions can be kept in sync. To create a Backend module, run `yarn new`, select `backend-module`, and fill out the rest of the prompts. This will create a new package at `plugins/-backend-module-`.