diff --git a/.changeset/remove-multiple-attachment-points-frontend-app-api.md b/.changeset/remove-multiple-attachment-points-frontend-app-api.md new file mode 100644 index 0000000000..4d54ef599f --- /dev/null +++ b/.changeset/remove-multiple-attachment-points-frontend-app-api.md @@ -0,0 +1,5 @@ +--- +'@backstage/frontend-app-api': patch +--- + +**DEPRECATED**: Deprecated support for multiple attachment points. diff --git a/.changeset/remove-multiple-attachment-points-frontend-plugin-api.md b/.changeset/remove-multiple-attachment-points-frontend-plugin-api.md new file mode 100644 index 0000000000..b0d5739ea3 --- /dev/null +++ b/.changeset/remove-multiple-attachment-points-frontend-plugin-api.md @@ -0,0 +1,7 @@ +--- +'@backstage/frontend-plugin-api': patch +--- + +**DEPRECATED**: Multiple attachment points for extensions have been deprecated. The functionality continues to work for backward compatibility, but will log a deprecation warning and be removed in a future release. + +Extensions using array attachment points should migrate to using Utility APIs instead. See the [Sharing Extensions Across Multiple Locations](https://backstage.io/docs/frontend-system/architecture/27-sharing-extensions) guide for the recommended pattern. diff --git a/.changeset/scaffolder-form-fields-api-migration-react.md b/.changeset/scaffolder-form-fields-api-migration-react.md new file mode 100644 index 0000000000..4d640c58fc --- /dev/null +++ b/.changeset/scaffolder-form-fields-api-migration-react.md @@ -0,0 +1,11 @@ +--- +'@backstage/plugin-scaffolder-react': patch +--- + +Scaffolder form fields in the new frontend system now use a Utility API pattern instead of multiple attachment points. The `FormFieldBlueprint` now uses this new approach, and while form fields created with older versions still work, they will produce a deprecation warning and will stop working in a future release. + +As part of this change, the following alpha exports were removed: + +- `formFieldsApi` +- `formFieldsApiRef` +- `ScaffolderFormFieldsApi` diff --git a/.changeset/scaffolder-form-fields-api-migration.md b/.changeset/scaffolder-form-fields-api-migration.md new file mode 100644 index 0000000000..cfbed3b749 --- /dev/null +++ b/.changeset/scaffolder-form-fields-api-migration.md @@ -0,0 +1,10 @@ +--- +'@backstage/plugin-scaffolder': patch +--- + +Scaffolder form fields in the new frontend system now use a Utility API pattern instead of multiple attachment points. The `FormFieldBlueprint` now uses this new approach, and while form fields created with older versions still work, they will produce a deprecation warning and will stop working in a future release. + +As part of this change, the following alpha exports were removed: + +- `formFieldsApiRef` +- `ScaffolderFormFieldsApi` diff --git a/.changeset/techdocs-addons-api-migration-react.md b/.changeset/techdocs-addons-api-migration-react.md new file mode 100644 index 0000000000..9a2c5f1da9 --- /dev/null +++ b/.changeset/techdocs-addons-api-migration-react.md @@ -0,0 +1,7 @@ +--- +'@backstage/plugin-techdocs-react': patch +--- + +TechDocs addons in the new frontend system now use a Utility API pattern instead of multiple attachment points. The `AddonBlueprint` now uses this new approach, and while addons created with older versions still work, they will produce a deprecation warning and will stop working in a future release. + +As part of this change, the `techDocsAddonDataRef` alpha export was removed. diff --git a/.changeset/techdocs-addons-api-migration.md b/.changeset/techdocs-addons-api-migration.md new file mode 100644 index 0000000000..f2e481de7e --- /dev/null +++ b/.changeset/techdocs-addons-api-migration.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-techdocs': patch +--- + +TechDocs addons in the new frontend system now use a Utility API pattern instead of multiple attachment points. The `AddonBlueprint` now uses this new approach, and while addons created with older versions still work, they will produce a deprecation warning and will stop working in a future release. diff --git a/docs/frontend-system/architecture/20-extensions.md b/docs/frontend-system/architecture/20-extensions.md index c13a54427a..99b77f5448 100644 --- a/docs/frontend-system/architecture/20-extensions.md +++ b/docs/frontend-system/architecture/20-extensions.md @@ -337,23 +337,11 @@ const routableExtension = createExtension({ }); ``` -## Multiple attachment points +## Sharing extensions across multiple locations -For some cases it can be useful to attach extensions to multiple parents. An example of this are Scaffolder field extensions or TechDocs addons that are consumed by multiple extensions. Specifying multiple attachments is done by providing an array of attachment points to the `attachTo` property of the extension. Keep in mind that this increases the complexity of your extension tree and should only be done when necessary. The following example shows how to attach our example extension to multiple parents: +If you need to make extensions available in multiple locations throughout your app, use a Utility API that collects the extensions and allows multiple parent extensions to consume them. This pattern provides better separation of concerns and makes data flow more explicit. -```tsx -const extension = createExtension({ - name: 'my-extension', - attachTo: [ - { id: 'my-first-parent', input: 'content' }, - { id: 'my-second-parent', input: 'children' }, // The input names do not need to match - ], - output: [coreExtensionData.reactElement], - factory() { - return [coreExtensionData.reactElement(
Section Content
)]; diff --git a/docs/frontend-system/architecture/27-sharing-extensions.md b/docs/frontend-system/architecture/27-sharing-extensions.md new file mode 100644 index 0000000000..a08fd7d1db --- /dev/null +++ b/docs/frontend-system/architecture/27-sharing-extensions.md @@ -0,0 +1,173 @@ +--- +id: sharing-extensions +title: Sharing Extensions Across Multiple Locations +sidebar_label: Sharing Extensions +description: Using Utility APIs to share extensions across multiple locations in your app +--- + +Some plugins may need to provide extensibility that can be reused in multiple locations throughout the app. For example, in the pattern demonstrated on this page, a plugin can be made extensible by allowing widgets to be contributed that are then rendered on multiple pages. To achieve this, the recommended pattern is to use a Utility API that collects the extensions and makes them available throughout the plugin or the app. + +## Overview + +This pattern combines a Utility API with an extension blueprint to: + +1. Define the extension data types and API interface +2. Provide a blueprint for creating extensions +3. Create a Utility API extension that collects extensions as input +4. Consume the extensions via the API + +This approach provides a native integration with the frontend system, allowing to further rely on features like making the extensions configurable or have further extension points. + +## Basic Pattern + +The following example demonstrates this pattern using widgets that can be displayed on multiple pages. However, this pattern is flexible and can be adapted for many different scenarios where you need to: + +- Share the same type of extension across different pages or views +- Allow third-party plugins to contribute extensions in a decoupled way +- Aggregate similar functionality from multiple sources in a consistent way + +The core concepts remain the same regardless of what type of functionality you're sharing. + +### 1. Define the Extension Data Types and API Interface + +First, in your plugin's `-react` package (e.g., `backstage-plugin-foo-react`), define the widget types and API interface: + +```tsx title="in backstage-plugin-foo-react" +import { createApiRef } from '@backstage/frontend-plugin-api'; +import { ComponentType } from 'react'; + +export interface FooWidgetProps { + title: string; +} + +// Define what data each widget provides, prefer using lazy loading for large pieces of functionality like components +export interface FooWidget { + title: string; + size: 'small' | 'medium' | 'large'; + loader: () => Promise(
data: TechDocsAddonOptions,
) => void;
-// @alpha (undocumented)
-export const techDocsAddonDataRef: ConfigurableExtensionDataRef<
- TechDocsAddonOptions,
- 'techdocs.addon',
- {}
->;
-
// @public
export const TechDocsAddonLocations: Readonly<{
readonly Header: 'Header';
diff --git a/plugins/techdocs-react/src/alpha.ts b/plugins/techdocs-react/src/alpha.ts
index 83c0444753..031ec6711f 100644
--- a/plugins/techdocs-react/src/alpha.ts
+++ b/plugins/techdocs-react/src/alpha.ts
@@ -29,8 +29,7 @@ import {
/** @alpha */
export type { TechDocsAddonOptions, TechDocsAddonLocations } from './types';
-/** @alpha */
-export const techDocsAddonDataRef =
+const techDocsAddonDataRef =
createExtensionDataRef