Hello World
,
- };
+ return [coreExtensionData.reactElement(Hello World
)];
},
});
```
-Note that while the `createExtension` is public API and used in many places, it is not typically what you use when building plugins and features. Instead there are many extension creator functions exported by both the core APIs and plugins that make it easier to create extensions for more specific usages.
+Note that while the `createExtension` function is public API and used in many places, it is not typically what you use when building plugins and features. Instead there are many [extension blueprints](./23-extension-blueprints.md) exported by both the core APIs and plugins that make it easier to create extensions for more specific usages.
-## Extension Data
+## Extension data
Communication between extensions happens in one direction, from one child extension through the attachment point to its parent. The child extension outputs data which is then passed as inputs to the parent extension. This data is called Extension Data, where the shape of each individual piece of data is described by an Extension Data Reference. These references are created separately from the extensions themselves, and can be shared across multiple different kinds of extensions. Each reference consists of an ID and a TypeScript type that the data needs to conform to, and represents one type of data that can be shared between extensions.
-### Extension Data References
+### Extension data references
To create a new extension data reference to represent a type of shared extension data you use the `createExtensionDataRef` function. When defining a new reference you need to provide an ID and a TypeScript type, for example:
@@ -101,59 +95,53 @@ The `ExtensionDataRef` can then be used to describe an output property of the ex
```tsx
const extension = createExtension({
// ...
- output: {
- element: reactElementExtensionDataRef,
- },
+ output: [reactElementExtensionDataRef],
factory() {
- return {
- element: Hello World
,
- };
+ return [reactElementExtensionDataRef(Hello World
)];
},
});
```
-### Extension Data Uniqueness
+### Extension data uniqueness
-Note that the key used in the output map, in this case `element`, is only used internally within the definition of the extension itself. That actual identifier for the data when consumed by other extensions is the ID of the reference, in this case [`core.reactElement`](https://github.com/backstage/backstage/blob/916da47e8abdb880877daa18881eb8fdbb33e70a/packages/frontend-plugin-api/src/wiring/coreExtensionData.ts#L23). This means that you can not output multiple different values for the same extension data reference, as they would conflict with each other. That in turn makes overly generic extension data references a bad idea, for example a generic "string" type. Instead create separate references for each type of data that you want to share.
+Note that you are **not** allowed to repeat the same data reference in the outputs, or return multiple values for the same reference. Multiple outputs for the same reference will conflict with each other and cause an error. If you want to output multiple values of the same TypeScript type you should create separate references for each value. That in turn means that overly generic extension data references are a bad idea, for example a generic "string" type. Instead create separate references for each type of data that you want to share.
```tsx
const extension = createExtension({
// ...
- output: {
- // ❌ Bad example - outputting values of same type
- element1: reactElementExtensionDataRef,
- element2: reactElementExtensionDataRef,
- },
+ output: [
+ // ❌ Bad example - duplicate output declaration
+ reactElementExtensionDataRef,
+ reactElementExtensionDataRef,
+ ],
factory() {
- return {
- element1: Hello World
,
- element2: Hello World
,
- };
+ return [
+ // ❌ Bad example - duplicate output values
+ reactElementExtensionDataRef(Hello
),
+ reactElementExtensionDataRef(World
),
+ ];
},
});
```
-### Core Extension Data
+### Core extension data
We provide default `coreExtensionData`, which provides commonly used `ExtensionDataRef`s - e.g. for `React.JSX.Element` and `RouteRef`. They can be used when creating your own extension. For example, the React Element extension data that we defined above is already provided as `coreExtensionData.reactElement`.
For a full list and explanations of all types of core extension data, see the [core extension data reference](../building-plugins/04-built-in-data-refs.md).
-### Optional Extension Data
+### Optional extension data
By default all extension data is required, meaning that the extension factory must provide a value for each output. However, it is possible to make extension data optional by calling the `.optional()` method. This makes it optional for the factory function to return a value as part of its output. When calling the `.optional()` method you create a new copy of the extension data reference, it does not mutate the existing reference.
```tsx
const extension = createExtension({
// ...
- output: {
- element: coreExtensionData.reactElement.optional(),
- },
+ output: [coreExtensionData.reactElement.optional()],
factory() {
- return {
- element:
- Math.random() < 0.5 ? 
: undefined,
- };
+ return Math.random() > 0.5
+ ? [coreExtensionData.reactElement(Hello World
)]
+ : [];
},
});
```
@@ -167,17 +155,19 @@ const navigationExtension = createExtension({
// ...
inputs: {
// [1]: Input
- logo: createExtensionInput(
- {
- element: coreExtensionData.reactElement,
- },
- { singleton: true, optional: true },
- ),
+ logo: createExtensionInput([coreExtensionData.reactElement], {
+ singleton: true,
+ optional: true,
+ }),
},
factory({ inputs }) {
return {
element: (
-
+
),
};
},
@@ -193,10 +183,9 @@ So how can we now attach the output to the parent extension's input? If we think
const navigationItemExtension = createExtension({
// ...
attachTo: { id: 'app/nav', input: 'items' },
+ output: [coreExtensionData.reactElement],
factory() {
- return {
- element: Home,
- };
+ return [coreExtensionData.reactElement(Home)];
},
});
@@ -205,26 +194,22 @@ const navigationExtension = createExtension({
// [2]: Extension `id` will be `app/nav` following the extension naming pattern
namespace: 'app',
name: 'nav',
- output: {
- element: coreExtensionData.reactElement,
- },
+ output: [coreExtensionData.reactElement],
inputs: {
- items: createExtensionInput({
- element: coreExtensionData.reactElement,
- }),
+ items: createExtensionInput([coreExtensionData.reactElement]),
},
factory({ inputs }) {
- return {
- element: (
+ return [
+ coreExtensionData.reactElement(
+ ,
),
- };
+ ];
},
// ...
});
@@ -232,27 +217,27 @@ const navigationExtension = createExtension({
In this case the extension input `items` is an array, where each individual item is an extension that attached itself to the extension inputs of this `id`.
-With the `inputs` not only the `output` of an extensions item is passed to the extension, but also the `node`. However, it is discouraged to consume the `node` here unless needed. If we are looking at the `factory` function from the example above we could access the `node` like the following:
+In addition to being able to access data passed through the input, you also have access to the underlying app `node`. This can be useful if you for example want to get the ID of the attached extension. However, avoid using the `node` unless needed, it is generally better to stick to only consuming the provided data. If we are looking at the `factory` function from the example above we could access the `node` like the following:
```tsx
// ...
factory({ inputs }) {
- return {
- element: (
+ return [
+ coreExtensionData.reactElement(
),
- };
+ ];
},
```
-## Extension Configuration
+## Extension configuration
With the `app-config.yaml` there is already the option to pass configuration to plugins or the app to e.g. define the `baseURL` of your app. For extensions this concept would be limiting as an extension can be independent of the plugin & initiated several times. Therefore we created a possibility to configure each extension individually through config. The extension config schema is created using the [`zod`](https://zod.dev/) library, which in addition to TypeScript type checking also provides runtime validation and coercion. If we continue with the example of the `navigationExtension` and now want it to contain a configurable title, we could make it available like the following:
@@ -262,20 +247,20 @@ const navigationExtension = createExtension({
namespace: 'app',
name: 'nav',
// [3]: Extension `id` will be `app/nav` following the extension naming pattern
- configSchema: createSchemaFromZod(z =>
- z.object({
- title: z.string().default('Sidebar Title'),
- }),
- ),
+ config: {
+ schema: {
+ title: z => z.string().default('Sidebar Title'),
+ },
+ },
factory({ config }) {
- return {
- element: (
+ return [
+ coreExtensionData.reactElement(
+ ,
),
- };
+ ];
},
// ...
});
@@ -293,47 +278,40 @@ app:
title: 'Backstage'
```
-## Extension Creators
+## Extension factory as a generator function
-With creating an extension by using `createExtension(...)` you have the advantage that the extension can be anything in your Backstage application. We realised that this comes with the trade-off of having to repeat boilerplate code for similar building blocks. Here extension creators come into play for covering common building blocks in Backstage like pages using `createPageExtension`, themes using the `createThemeExtension` or items for the navigation using `createNavItemExtension`.
+In all examples so far we have defined the extension factory as a regular function that returns its output in an array. However, the only requirement is that the factory function returns any iterable of extension data values. This means that you can also define the factory function as a generator function, which allows you to yield values one by one. This is particularly useful if you want to conditionally output values.
-If we follow the example from above all items of the navigation have similarities, like they all want to be attached to the same extension with the same input as well as rendering the same navigation item component. Therefore `createExtension` can be abstracted for this use case to `createNavItemExtension` and if we add the extension to the app it will end up in the right place & looks like we expect a navigation item to look.
+For example, this is how we could define an extension where its output depends on the configuration:
```tsx
-export const HomeNavIcon = createNavItemExtension({
- routeRef: routeRefForTheHomePage,
- title: 'Home',
- icon: HomeIcon,
+const exampleExtension = createExtension({
+ // ...
+ config: {
+ schema: {
+ disableIcon: z.boolean().default(false),
+ },
+ },
+ output: [coreExtensionData.reactElement, iconDataRef.optional()],
+ *factory({ config }) {
+ yield coreExtensionData.reactElement(Hello World
);
+
+ if (!config.disableIcon) {
+ yield iconDataRef(Index Page
- - See "Foo" details - + {/* highlight-next-line */} + {getDetailsPath && ( + + See "Foo" details + + )}Index Page
- {/* highlight-next-line */} - Create Component + {/* highlight-start */} + {getCreateComponentPath && ( + Create Component + )} + {/* highlight-end */}
-
- );
-};
-```
-
## Sub Route References
The last kind of route ref that can be created is a `SubRouteRef`, which can be used to create a route ref with a fixed path relative to an absolute `RouteRef`. They are useful if you have a page that internally is mounted at a sub route of a page extension component, and you want other plugins to be able to route to that page. And they can be a useful utility to handle routing within a plugin itself as well.
@@ -368,17 +338,21 @@ import { DetailsPage } from './DetailsPage';
export const IndexPage = () => {
const { pathname } = useLocation();
+
+ // highlight-start
const getIndexPath = useRouteRef(indexRouteRef);
const getDetailsPath = useRouteRef(detailsSubRouteRef);
+ // highlight-end
+
return (
Index Page
- {/* Rendering the link only if the getCreateComponentPath is defined */} - {/* highlight-start */} - {getCreateComponentPath && ( - Create Component - )} - {/* highlight-end */} -Index Page
{/* Linking to the details sub route */} - {pathname === getIndexPath() ? ( - // highlight-start + {/* highlight-start */} + {pathname === getIndexPath?.() ? ( { > Show details - // highlight-end + {/* highlight-end */} ) : ( - // highlight-next-line - Hide details + {/* highlight-next-line */} + Hide details )} {/* Registering the details sub route */}My custom home page
); + }, + }), + ], + }); + ``` + +- a65cfc8: Add support for accessing extensions definitions provided by a plugin via `plugin.getExtension(...)`. For this to work the extensions must be defined using the v2 format, typically using an extension blueprint. + +- 34f1b2a: Support merging of `inputs` in extension blueprints, but stop merging `output`. In addition, the original factory in extension blueprints now returns a data container that both provides access to the returned data, but can also be forwarded as output. + +- 2d21599: Added support for being able to override extension definitions. + + ```tsx + const TestCard = EntityCardBlueprint.make({ + ... + }); + + TestCard.override({ + // override attachment points + attachTo: { id: 'something-else', input: 'overridden' }, + // extend the config schema + config: { + schema: { + newConfig: z => z.string().optional(), + } + }, + // override factory + *factory(originalFactory, { inputs, config }){ + const originalOutput = originalFactory(); + + yield coreExentsionData.reactElement( +
- op
+ params: {
+ defaultPath: '/',
+ routeRef: indexRouteRef,
+ loader: async () => {
+ const Component = () => {
+ const page1Link = useRouteRef(page1RouteRef);
+ return (
- );
- };
- return
- Page 1
-
-
- Home
-
-
- GraphiQL
-
-
- Search
-
-
- Settings
-
-
-
- );
- };
- return This is page 1
- Go back - Page 2 - {/* Page 2 */} - Page X - -
- Sub-page content:
+ op
+ {page1Link && (
+
-
+ Page 1
+
+ )}
-
- This is also page 1} />
- This is page 2} />
-
+ Home
+
+
+ GraphiQL
+
+
+ Search
+
+
+ Settings
+
+ );
+ };
+ return This is page 1
+ {indexLink && Go back} + Page 2 + {/* Page 2 */} + {xLink && Page X} + +
+ Sub-page content:
+
+
+
+ This is also page 1} />
+ This is page 2} />
+
+
+
-
- );
- };
- return This is page X
- Go back -
+
+ );
+ };
+ return