From 87b6e03693198482f257280297320bcef9236742 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 14 Aug 2024 12:08:37 +0200 Subject: [PATCH 1/5] docs/frontend-system: make space in architecture docs Signed-off-by: Patrik Oldsberg --- .../architecture/{01-index.md => 00-index.md} | 0 .../architecture/{02-app.md => 10-app.md} | 6 +++--- .../architecture/{04-plugins.md => 15-plugins.md} | 0 .../{03-extensions.md => 20-extensions.md} | 4 ++-- ...sion-overrides.md => 25-extension-overrides.md} | 2 +- .../{08-references.md => 30-references.md} | 0 .../{06-utility-apis.md => 33-utility-apis.md} | 2 +- .../architecture/{07-routes.md => 36-routes.md} | 0 ...08-naming-patterns.md => 50-naming-patterns.md} | 0 docs/frontend-system/building-apps/01-index.md | 4 ++-- .../building-apps/03-built-in-extensions.md | 2 +- docs/frontend-system/building-apps/08-migrating.md | 14 +++++++------- docs/frontend-system/building-plugins/01-index.md | 14 +++++++------- .../frontend-system/building-plugins/02-testing.md | 2 +- .../building-plugins/03-extension-types.md | 2 +- .../building-plugins/04-built-in-data-refs.md | 2 +- docs/frontend-system/utility-apis/01-index.md | 2 +- docs/frontend-system/utility-apis/02-creating.md | 2 +- .../frontend-system/utility-apis/04-configuring.md | 4 ++-- docs/plugins/composability.md | 4 ++-- microsite/sidebars.json | 6 +++--- 21 files changed, 36 insertions(+), 36 deletions(-) rename docs/frontend-system/architecture/{01-index.md => 00-index.md} (100%) rename docs/frontend-system/architecture/{02-app.md => 10-app.md} (95%) rename docs/frontend-system/architecture/{04-plugins.md => 15-plugins.md} (100%) rename docs/frontend-system/architecture/{03-extensions.md => 20-extensions.md} (99%) rename docs/frontend-system/architecture/{05-extension-overrides.md => 25-extension-overrides.md} (99%) rename docs/frontend-system/architecture/{08-references.md => 30-references.md} (100%) rename docs/frontend-system/architecture/{06-utility-apis.md => 33-utility-apis.md} (97%) rename docs/frontend-system/architecture/{07-routes.md => 36-routes.md} (100%) rename docs/frontend-system/architecture/{08-naming-patterns.md => 50-naming-patterns.md} (100%) diff --git a/docs/frontend-system/architecture/01-index.md b/docs/frontend-system/architecture/00-index.md similarity index 100% rename from docs/frontend-system/architecture/01-index.md rename to docs/frontend-system/architecture/00-index.md diff --git a/docs/frontend-system/architecture/02-app.md b/docs/frontend-system/architecture/10-app.md similarity index 95% rename from docs/frontend-system/architecture/02-app.md rename to docs/frontend-system/architecture/10-app.md index 3b839d4232..532971d124 100644 --- a/docs/frontend-system/architecture/02-app.md +++ b/docs/frontend-system/architecture/10-app.md @@ -33,13 +33,13 @@ const rootEl = document.getElementById('root')!; ReactDOM.createRoot(rootEl).render(app); ``` -We call `createApp` to create a new app instance, which is responsible for wiring together all of the features that we provide to the app. It also provides a set of built-in [Extensions](./03-extensions.md) that help build out the foundations of the app, as well as defaults for many other systems such as [Utility API](./06-utility-apis.md) implementations, components, icons, themes, and how to load configuration. No real work is done at the point of creating the app though, it's all deferred to the rendering of the element returned from `app.createRoot()`. +We call `createApp` to create a new app instance, which is responsible for wiring together all of the features that we provide to the app. It also provides a set of built-in [Extensions](./20-extensions.md) that help build out the foundations of the app, as well as defaults for many other systems such as [Utility API](./33-utility-apis.md) implementations, components, icons, themes, and how to load configuration. No real work is done at the point of creating the app though, it's all deferred to the rendering of the element returned from `app.createRoot()`. -It is possible to explicitly install features when creating the app, although typically these will instead be discovered automatically which we'll explore later on. Nevertheless these features are what build out the actual functionality of the app by providing [Extensions](./03-extensions.md). These extensions are wired together by the app into a tree structure known as the app extension tree. Each node in this tree receives data from its child nodes, and passes along data to its parent. The following diagram illustrates the shape of a small app extension tree. +It is possible to explicitly install features when creating the app, although typically these will instead be discovered automatically which we'll explore later on. Nevertheless these features are what build out the actual functionality of the app by providing [Extensions](./20-extensions.md). These extensions are wired together by the app into a tree structure known as the app extension tree. Each node in this tree receives data from its child nodes, and passes along data to its parent. The following diagram illustrates the shape of a small app extension tree. ![frontend system app structure diagram](../../assets/frontend-system/architecture-app.drawio.svg) -Each node in this tree is an extension with a parent node and children. The colored shapes represent extension data inputs and output, where each color is one unique type of data. You can see that there are both extensions that output data that is ignored by the parent, as well as extensions that accept inputs but do not have any children. There are a couple of different tools at your disposal when creating and extension that lets you define different requirements for your inputs and output, which we will cover in greater details in the [Extensions](./03-extensions.md) section. +Each node in this tree is an extension with a parent node and children. The colored shapes represent extension data inputs and output, where each color is one unique type of data. You can see that there are both extensions that output data that is ignored by the parent, as well as extensions that accept inputs but do not have any children. There are a couple of different tools at your disposal when creating and extension that lets you define different requirements for your inputs and output, which we will cover in greater details in the [Extensions](./20-extensions.md) section. A common type of data that is shared between extensions is React elements and components. These can in turn be rendered by each other in their own React components, which ends up forming a parallel tree of React components that is similar in shape to that of the app extension tree. At the top of the app extension tree is a built-in root extension that among other things outputs a React element. This element also ends up being the root of the parallel React tree, and is rendered by the React element returned by `app.createRoot()`. diff --git a/docs/frontend-system/architecture/04-plugins.md b/docs/frontend-system/architecture/15-plugins.md similarity index 100% rename from docs/frontend-system/architecture/04-plugins.md rename to docs/frontend-system/architecture/15-plugins.md diff --git a/docs/frontend-system/architecture/03-extensions.md b/docs/frontend-system/architecture/20-extensions.md similarity index 99% rename from docs/frontend-system/architecture/03-extensions.md rename to docs/frontend-system/architecture/20-extensions.md index 2f3daba6f8..eec9947c97 100644 --- a/docs/frontend-system/architecture/03-extensions.md +++ b/docs/frontend-system/architecture/20-extensions.md @@ -8,7 +8,7 @@ description: Frontend extensions > **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.** -As mentioned in the [previous section](./02-app.md), Backstage apps are built up from a tree of extensions. This section will go into more detail about what extensions are, how to create and use them, and how to create your own extensibility patterns. +As mentioned in the [previous section](./10-app.md), Backstage apps are built up from a tree of extensions. This section will go into more detail about what extensions are, how to create and use them, and how to create your own extensibility patterns. ## Extension Structure @@ -317,7 +317,7 @@ The `id` of the extension is then build out of `namespace`, `name` & `kind` like id: kind:namespace/name ``` -For more information on naming of extension refer to the [naming patterns documentation](./08-naming-patterns.md). +For more information on naming of extension refer to the [naming patterns documentation](./50-naming-patterns.md). ### Extension Creators in libraries diff --git a/docs/frontend-system/architecture/05-extension-overrides.md b/docs/frontend-system/architecture/25-extension-overrides.md similarity index 99% rename from docs/frontend-system/architecture/05-extension-overrides.md rename to docs/frontend-system/architecture/25-extension-overrides.md index 41702e6823..42a7f365a1 100644 --- a/docs/frontend-system/architecture/05-extension-overrides.md +++ b/docs/frontend-system/architecture/25-extension-overrides.md @@ -89,7 +89,7 @@ Note that it can still be a good idea to split your overrides out into separate To override an extension that is provided by a plugin, you need to provide a new extension that has the same ID as the existing extension. That is, all kind, namespace, and name options must match the extension you want to replace. This means that you typically need to provide an explicit `namespace` when overriding extensions from a plugin. :::info -We recommend that plugin developers share the extension IDs in their plugin documentation, but usually you can infer the ID by following the [naming patterns](./08-naming-patterns.md) documentation. +We recommend that plugin developers share the extension IDs in their plugin documentation, but usually you can infer the ID by following the [naming patterns](./50-naming-patterns.md) documentation. ::: ### Example diff --git a/docs/frontend-system/architecture/08-references.md b/docs/frontend-system/architecture/30-references.md similarity index 100% rename from docs/frontend-system/architecture/08-references.md rename to docs/frontend-system/architecture/30-references.md diff --git a/docs/frontend-system/architecture/06-utility-apis.md b/docs/frontend-system/architecture/33-utility-apis.md similarity index 97% rename from docs/frontend-system/architecture/06-utility-apis.md rename to docs/frontend-system/architecture/33-utility-apis.md index 49e5854b65..c20936f819 100644 --- a/docs/frontend-system/architecture/06-utility-apis.md +++ b/docs/frontend-system/architecture/33-utility-apis.md @@ -10,7 +10,7 @@ description: Utility APIs ## Overview -Utility APIs are pieces of standalone functionality, interfaces that can be requested by plugins to use. They are defined by a TypeScript interface as well as a reference (an "API ref") used to access its implementation. They can be provided both by plugins and the core framework, and are themselves [extensions](../architecture/03-extensions.md) that can have inputs, be replaced, and be declaratively configured in your app-config. +Utility APIs are pieces of standalone functionality, interfaces that can be requested by plugins to use. They are defined by a TypeScript interface as well as a reference (an "API ref") used to access its implementation. They can be provided both by plugins and the core framework, and are themselves [extensions](../architecture/20-extensions.md) that can have inputs, be replaced, and be declaratively configured in your app-config. A common example of a utility API is a client interface to interact with the backend part of a plugin, such as the catalog client. Any frontend plugin can then request an implementation of that interface to make requests through. diff --git a/docs/frontend-system/architecture/07-routes.md b/docs/frontend-system/architecture/36-routes.md similarity index 100% rename from docs/frontend-system/architecture/07-routes.md rename to docs/frontend-system/architecture/36-routes.md diff --git a/docs/frontend-system/architecture/08-naming-patterns.md b/docs/frontend-system/architecture/50-naming-patterns.md similarity index 100% rename from docs/frontend-system/architecture/08-naming-patterns.md rename to docs/frontend-system/architecture/50-naming-patterns.md diff --git a/docs/frontend-system/building-apps/01-index.md b/docs/frontend-system/building-apps/01-index.md index ea7fe20948..bb09fb6907 100644 --- a/docs/frontend-system/building-apps/01-index.md +++ b/docs/frontend-system/building-apps/01-index.md @@ -66,7 +66,7 @@ Linking routes from different plugins requires this configuration. You can do th ### Enable feature discovery -Use this setting to enable experimental feature discovery when building your app with `@backstage/cli`. With this configuration your application tries to discover and install package extensions automatically, check [here](../architecture/02-app.md#feature-discovery) for more details. +Use this setting to enable experimental feature discovery when building your app with `@backstage/cli`. With this configuration your application tries to discover and install package extensions automatically, check [here](../architecture/10-app.md#feature-discovery) for more details. :::warning Remember that package extensions that are not auto-discovered must be manually added to the application when creating an app. See [features](#install-features-manually) for more details. @@ -99,7 +99,7 @@ export default app.createRoot(); ``` :::info -You can also pass overrides to the features array, for more details, please read the [extension overrides](../architecture/05-extension-overrides.md) documentation. +You can also pass overrides to the features array, for more details, please read the [extension overrides](../architecture/25-extension-overrides.md) documentation. ::: ### Using an async features loader diff --git a/docs/frontend-system/building-apps/03-built-in-extensions.md b/docs/frontend-system/building-apps/03-built-in-extensions.md index a5e6476eb0..5f74100df0 100644 --- a/docs/frontend-system/building-apps/03-built-in-extensions.md +++ b/docs/frontend-system/building-apps/03-built-in-extensions.md @@ -24,7 +24,7 @@ Be careful when disabling built-in extensions, as there may be other extensions ## Override built-in extensions -You can override any built-in extension whenever their customizations, whether through configuration or input, do not meet a use case for your Backstage instance. Check out [this](../architecture/05-extension-overrides.md) documentation on how to override application extensions. +You can override any built-in extension whenever their customizations, whether through configuration or input, do not meet a use case for your Backstage instance. Check out [this](../architecture/25-extension-overrides.md) documentation on how to override application extensions. :::warning Be aware there could be some implementation requirements to properly override an built-in extension, such as using same apis and do not remove inputs or configurations otherwise you can cause a side effect in other parts of the system that expects same minimal behavior. diff --git a/docs/frontend-system/building-apps/08-migrating.md b/docs/frontend-system/building-apps/08-migrating.md index 716e0da772..5d92478661 100644 --- a/docs/frontend-system/building-apps/08-migrating.md +++ b/docs/frontend-system/building-apps/08-migrating.md @@ -23,7 +23,7 @@ import { createApp } from '@backstage/frontend-app-api'; This immediate switch will lead to a lot of breakages that we need to fix. -Let's start by addressing the change to `app.createRoot(...)`, which no longer accepts any arguments. This represents a fundamental change that the new frontend system introduces. In the old system the app element tree that you passed to `app.createRoot(...)` was the primary way that you installed and configured plugins and features in your app. In the new system this is instead replaced by extensions that are wired together into an extension tree. Much more responsibility has now been shifted to plugins, for example you no longer have to manually provide the route path for each plugin page, but instead only configure it if you want to override the default. For more information on how the new system works, see the [architecture](../architecture/01-index.md) section. +Let's start by addressing the change to `app.createRoot(...)`, which no longer accepts any arguments. This represents a fundamental change that the new frontend system introduces. In the old system the app element tree that you passed to `app.createRoot(...)` was the primary way that you installed and configured plugins and features in your app. In the new system this is instead replaced by extensions that are wired together into an extension tree. Much more responsibility has now been shifted to plugins, for example you no longer have to manually provide the route path for each plugin page, but instead only configure it if you want to override the default. For more information on how the new system works, see the [architecture](../architecture/00-index.md) section. Given that the app element tree is most of what builds up the app, it's likely also going to be the majority of the migration effort. In order to make the migration as smooth as possible we have provided a helper that lets you convert an existing app element tree into plugins that you can install in a new app. This in turn allows for a gradual migration of individual plugins, rather than needing to migrate the entire app structure at once. @@ -95,7 +95,7 @@ At this point the contents of your app should be past the initial migration stag ## Migrating `createApp` Options -Many of the `createApp` options have been migrated to use extensions instead. Each will have their own [extension creator](../architecture/03-extensions.md#extension-creators) that you use to create a custom extension. To add these standalone extensions to the app they need to be passed to `createExtensionOverrides`, which bundles them into a _feature_ that you can install in the app. See the [standalone extensions](../architecture/05-extension-overrides.md#create-standalone-extensions) section for more information. +Many of the `createApp` options have been migrated to use extensions instead. Each will have their own [extension creator](../architecture/20-extensions.md#extension-creators) that you use to create a custom extension. To add these standalone extensions to the app they need to be passed to `createExtensionOverrides`, which bundles them into a _feature_ that you can install in the app. See the [standalone extensions](../architecture/25-extension-overrides.md#create-standalone-extensions) section for more information. For example, assuming you have a `lightTheme` extension that you want to add to your app, you can use the following: @@ -176,7 +176,7 @@ createApp({ }); ``` -Plugins don't even have to be imported manually after installing their package if [features discovery](../architecture/02-app.md#feature-discovery) is enabled. +Plugins don't even have to be imported manually after installing their package if [features discovery](../architecture/10-app.md#feature-discovery) is enabled. ```yaml title="in app-config.yaml" app: @@ -219,7 +219,7 @@ createPlugin({ Many app components are now installed as extensions instead using `createComponentExtension`. See the section on [configuring app components](./01-index.md#configure-your-app) for more information. -The `Router` component is now a built-in extension that you can [override](../architecture/05-extension-overrides.md) using `createRouterExtension`. +The `Router` component is now a built-in extension that you can [override](../architecture/25-extension-overrides.md) using `createRouterExtension`. The Sign-in page is now installed as an extension using the `createSignInPageExtension` instead. @@ -341,7 +341,7 @@ const app = createApp({ ### `bindRoutes` -Route bindings can still be done using this option, but you now also have the ability to bind routes using static configuration instead. See the section on [binding routes](../architecture/07-routes.md#binding-external-route-references) for more information. +Route bindings can still be done using this option, but you now also have the ability to bind routes using static configuration instead. See the section on [binding routes](../architecture/36-routes.md#binding-external-route-references) for more information. Note that if you are binding routes from a legacy plugin that was converted using `convertLegacyApp`, you will need to use the `convertLegacyRouteRefs` and/or `convertLegacyRouteRef` to convert the routes to be compatible with the new system. @@ -470,7 +470,7 @@ const routes = ( ); ``` -If you are using [app feature discovery](../architecture/02-app.md#feature-discovery) the installation step is simple, it's already done! The new version of the scaffolder plugin was already discovered and present in the app, it was simply disabled because the plugin created from the legacy route had higher priority. If you do not use feature discovery, you will instead need to manually install the new scaffolder plugin in your app through the `features` option of `createApp`. +If you are using [app feature discovery](../architecture/10-app.md#feature-discovery) the installation step is simple, it's already done! The new version of the scaffolder plugin was already discovered and present in the app, it was simply disabled because the plugin created from the legacy route had higher priority. If you do not use feature discovery, you will instead need to manually install the new scaffolder plugin in your app through the `features` option of `createApp`. Continue this process for each of your legacy routes until you have migrated all of them. For any plugin with additional extensions installed as children of the `Route`, refer to the plugin READMEs for more detailed instructions. For the entity pages, refer to the [separate section](#entity-pages). @@ -482,7 +482,7 @@ The entity pages are typically defined in `packages/app/src/components/catalog` New apps feature a built-in sidebar extension (`app/nav`) that will render all nav item extensions provided by plugins. This is a placeholder implementation and not intended as a long-term solution. In the future we will aim to provide a more flexible sidebar extension that allows for more customization out of the box. -Because the built-in sidebar is quite limited you may want to override the sidebar with your own custom implementation. To do so, use `createExtension` directly and refer to the [original sidebar implementation](https://github.com/backstage/backstage/blob/master/packages/frontend-app-api/src/extensions/AppNav.tsx). The following is an example of how to take your existing sidebar from the `Root` component that you typically find in `packages/app/src/components/Root.tsx`, and use it in an [extension override](../architecture/05-extension-overrides.md): +Because the built-in sidebar is quite limited you may want to override the sidebar with your own custom implementation. To do so, use `createExtension` directly and refer to the [original sidebar implementation](https://github.com/backstage/backstage/blob/master/packages/frontend-app-api/src/extensions/AppNav.tsx). The following is an example of how to take your existing sidebar from the `Root` component that you typically find in `packages/app/src/components/Root.tsx`, and use it in an [extension override](../architecture/25-extension-overrides.md): ```tsx const nav = createExtension({ diff --git a/docs/frontend-system/building-plugins/01-index.md b/docs/frontend-system/building-plugins/01-index.md index f8d80f9382..618e660f2b 100644 --- a/docs/frontend-system/building-plugins/01-index.md +++ b/docs/frontend-system/building-plugins/01-index.md @@ -8,9 +8,9 @@ description: Building frontend plugins using the new frontend system > **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.** -This section covers how to build your own frontend [plugins](../architecture/04-plugins.md) and -[overrides](../architecture/05-extension-overrides.md). They are sometimes collectively referred to as -frontend _features_, and what you install to build up a Backstage frontend [app](../architecture/02-app.md). +This section covers how to build your own frontend [plugins](../architecture/15-plugins.md) and +[overrides](../architecture/25-extension-overrides.md). They are sometimes collectively referred to as +frontend _features_, and what you install to build up a Backstage frontend [app](../architecture/10-app.md). ## Creating a new plugin @@ -43,13 +43,13 @@ export { examplePlugin as default } from './plugin'; Note that we export the plugin as the default export of our package from `src/index.ts`. This is important, as it is how users of our plugin are able to seamlessly install the plugin package in a Backstage app without having to reference the plugin instance through code. -The plugin ID should be a lowercase dash-separated string, while the plugin instance variable should be the camel case version of the ID with a `Plugin` suffix. For more details on naming patterns within the frontend system, see [the article on naming patterns](../architecture/08-naming-patterns.md). By sticking to these naming patterns you ensure that users of your plugin more easily recognize the exports and features provided by your plugin. +The plugin ID should be a lowercase dash-separated string, while the plugin instance variable should be the camel case version of the ID with a `Plugin` suffix. For more details on naming patterns within the frontend system, see [the article on naming patterns](../architecture/50-naming-patterns.md). By sticking to these naming patterns you ensure that users of your plugin more easily recognize the exports and features provided by your plugin. ## Adding extensions -The plugin that we created above is empty, and doesn't provide any actual functionality. To add functionality to a plugin you need to create and provide it with one or more [extensions](../architecture/03-extensions.md). Let's continue by adding a standalone page to our plugin, as well as a navigation item that allows users to navigate to the page. +The plugin that we created above is empty, and doesn't provide any actual functionality. To add functionality to a plugin you need to create and provide it with one or more [extensions](../architecture/20-extensions.md). Let's continue by adding a standalone page to our plugin, as well as a navigation item that allows users to navigate to the page. -To create a new extension you typically use pre-defined [extension creators](../architecture/03-extensions.md#extension-creators), provided either by the framework itself or by other plugins. In this case we'll need to use `createPageExtension` and `createNavItemExtension`, both from `@backstage/frontend-plugin-api`. We will also need to [create a route reference](../architecture/07-routes.md#creating-a-route-reference) to use as a reference for out page, allowing us to dynamically create URLs that link to our page. +To create a new extension you typically use pre-defined [extension creators](../architecture/20-extensions.md#extension-creators), provided either by the framework itself or by other plugins. In this case we'll need to use `createPageExtension` and `createNavItemExtension`, both from `@backstage/frontend-plugin-api`. We will also need to [create a route reference](../architecture/36-routes.md#creating-a-route-reference) to use as a reference for out page, allowing us to dynamically create URLs that link to our page. ```tsx title="in src/routes.ts" import { createRouteRef } from '@backstage/frontend-plugin-api'; @@ -106,7 +106,7 @@ export const examplePlugin = createPlugin({ What we've built here is a very common type of plugin. It's a top-level tool that provides a single page, along with a method for navigating to that page. The implementation of the page component, in this case the highlighted `ExamplePage`, can be arbitrarily complex. It can be anything from a single simple information page, to a full-blown application with multiple sub-pages. -We have also provided external access to our route reference by passing it to the plugin `routes` option. This makes it possible for app integrators to bind an external link from a different plugin to our plugin page. You can read more about how this works in the [External Route References](../architecture/07-routes.md#external-route-references) section. +We have also provided external access to our route reference by passing it to the plugin `routes` option. This makes it possible for app integrators to bind an external link from a different plugin to our plugin page. You can read more about how this works in the [External Route References](../architecture/36-routes.md#external-route-references) section. ## Utility APIs diff --git a/docs/frontend-system/building-plugins/02-testing.md b/docs/frontend-system/building-plugins/02-testing.md index 26c9503c6d..f665ed0f0c 100644 --- a/docs/frontend-system/building-plugins/02-testing.md +++ b/docs/frontend-system/building-plugins/02-testing.md @@ -41,7 +41,7 @@ describe('Entity details component', () => { }); ``` -To mock [Utility APIs](../architecture/06-utility-apis.md) that are used by your component you can use the `TestApiProvider` to override individual API implementations. In the snippet below, we wrap the component within a `TestApiProvider` in order to mock the catalog client API: +To mock [Utility APIs](../architecture/33-utility-apis.md) that are used by your component you can use the `TestApiProvider` to override individual API implementations. In the snippet below, we wrap the component within a `TestApiProvider` in order to mock the catalog client API: ```tsx import React from 'react'; diff --git a/docs/frontend-system/building-plugins/03-extension-types.md b/docs/frontend-system/building-plugins/03-extension-types.md index 1f3baaa710..c7c2e2ab1f 100644 --- a/docs/frontend-system/building-plugins/03-extension-types.md +++ b/docs/frontend-system/building-plugins/03-extension-types.md @@ -8,7 +8,7 @@ description: Extension types provided by the frontend system and core features > **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.** -This section covers many of the [extension types](../architecture/03-extensions.md#extension-creators) available at your disposal when building Backstage frontend plugins. +This section covers many of the [extension types](../architecture/20-extensions.md#extension-creators) available at your disposal when building Backstage frontend plugins. ## Built-in extension types diff --git a/docs/frontend-system/building-plugins/04-built-in-data-refs.md b/docs/frontend-system/building-plugins/04-built-in-data-refs.md index dacbbf30f1..d13e734279 100644 --- a/docs/frontend-system/building-plugins/04-built-in-data-refs.md +++ b/docs/frontend-system/building-plugins/04-built-in-data-refs.md @@ -8,7 +8,7 @@ description: Configuring or overriding built-in extension data references > **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.** -To have a better understanding of extension data references please read [the corresponding architecture section](../architecture/03-extensions.md#extension-data) first. +To have a better understanding of extension data references please read [the corresponding architecture section](../architecture/20-extensions.md#extension-data) first. ## Built-in extension data references diff --git a/docs/frontend-system/utility-apis/01-index.md b/docs/frontend-system/utility-apis/01-index.md index 37120a5152..07f7dcc2a8 100644 --- a/docs/frontend-system/utility-apis/01-index.md +++ b/docs/frontend-system/utility-apis/01-index.md @@ -8,7 +8,7 @@ description: Working with Utility APIs in the New Frontend System > **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.** -As described [in the architecture section](../architecture/06-utility-apis.md), utility APIs are pieces of shared functionality - interfaces that can be requested by plugins to use. They are defined by a TypeScript interface as well as a reference (an "API ref") used to access its implementation. They can be provided both by plugins and the core framework, and are themselves [extensions](../architecture/03-extensions.md) that can accept inputs, be declaratively configured in your app-config, or transparently be replaced entirely with custom implementations that fulfill the same contract. +As described [in the architecture section](../architecture/33-utility-apis.md), utility APIs are pieces of shared functionality - interfaces that can be requested by plugins to use. They are defined by a TypeScript interface as well as a reference (an "API ref") used to access its implementation. They can be provided both by plugins and the core framework, and are themselves [extensions](../architecture/20-extensions.md) that can accept inputs, be declaratively configured in your app-config, or transparently be replaced entirely with custom implementations that fulfill the same contract. ## Creating utility APIs diff --git a/docs/frontend-system/utility-apis/02-creating.md b/docs/frontend-system/utility-apis/02-creating.md index fcb7ff1a65..77caaf55f0 100644 --- a/docs/frontend-system/utility-apis/02-creating.md +++ b/docs/frontend-system/utility-apis/02-creating.md @@ -86,7 +86,7 @@ For illustration we make a skeleton implementation class and the API extension a The code also illustrates how the API factory declares a dependency on another utility API - the core storage API in this case. An instance of that utility API is then provided to the factory function. -The resulting extension ID of the work API will be the kind `api:` followed by the plugin ID as the namespace, in this case ending up as `api:plugin.example.work`. Check out [the naming patterns doc](../architecture/08-naming-patterns.md) for more information on how this works. You can now use this ID to refer to the API in app-config and elsewhere. +The resulting extension ID of the work API will be the kind `api:` followed by the plugin ID as the namespace, in this case ending up as `api:plugin.example.work`. Check out [the naming patterns doc](../architecture/50-naming-patterns.md) for more information on how this works. You can now use this ID to refer to the API in app-config and elsewhere. ## Adding configurability diff --git a/docs/frontend-system/utility-apis/04-configuring.md b/docs/frontend-system/utility-apis/04-configuring.md index 7acf23decf..d22e10011b 100644 --- a/docs/frontend-system/utility-apis/04-configuring.md +++ b/docs/frontend-system/utility-apis/04-configuring.md @@ -12,7 +12,7 @@ Utility APIs are extensions and can therefore optionally be amended with configu ## Configuring -To configure your Utility API extension, first you'll need to know its ID. That ID is formed from the API ref ID; check [the naming patterns docs](../architecture/08-naming-patterns.md) for details. +To configure your Utility API extension, first you'll need to know its ID. That ID is formed from the API ref ID; check [the naming patterns docs](../architecture/50-naming-patterns.md) for details. Our example work API from [the creating section](./02-creating.md) would have the ID `api:plugin.example.work`. You configure it and all other extensions under the `app.extensions` section of your app-config. @@ -37,7 +37,7 @@ Well written input-enabled extension often have extension creator functions that ## Replacing a Utility API implementation -Like with other extension types, you replace Utility APIs with your own custom implementation using [extension overrides](../architecture/05-extension-overrides.md). +Like with other extension types, you replace Utility APIs with your own custom implementation using [extension overrides](../architecture/25-extension-overrides.md). ```tsx title="in your app" /* highlight-add-start */ diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md index 1a9c0babf9..a0e0e2d5e6 100644 --- a/docs/plugins/composability.md +++ b/docs/plugins/composability.md @@ -329,7 +329,7 @@ You can also use static configuration to bind routes, removing the need to make changes to the app code. It does however mean that you won't get type safety when binding routes and compile-time validation of the bindings. Static configuration of route bindings is done under the `app.routes.bindings` key in -`app-config.yaml`. It works the same way as [route bindings in the new frontend system](../frontend-system/architecture/07-routes.md#binding-external-route-references), +`app-config.yaml`. It works the same way as [route bindings in the new frontend system](../frontend-system/architecture/36-routes.md#binding-external-route-references), for example: ```yaml @@ -342,7 +342,7 @@ app: ### Default Targets for External Route References Following the `1.28` release of Backstage you can now define default targets for -external route references. They work the same way as [default targets in the new frontend system](../frontend-system/architecture/07-routes.md#default-targets-for-external-route-references), +external route references. They work the same way as [default targets in the new frontend system](../frontend-system/architecture/36-routes.md#default-targets-for-external-route-references), for example: ```ts diff --git a/microsite/sidebars.json b/microsite/sidebars.json index ddccb14c91..be17d76e03 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -452,13 +452,13 @@ "items": [ "frontend-system/architecture/index", "frontend-system/architecture/app", - "frontend-system/architecture/extensions", "frontend-system/architecture/plugins", + "frontend-system/architecture/extensions", "frontend-system/architecture/extension-overrides", + "frontend-system/architecture/references", "frontend-system/architecture/utility-apis", "frontend-system/architecture/routes", - "frontend-system/architecture/naming-patterns", - "frontend-system/architecture/references" + "frontend-system/architecture/naming-patterns" ] }, { From d61f075df212a78f012bbe3e5a3293a98af74507 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 14 Aug 2024 12:24:59 +0200 Subject: [PATCH 2/5] docs: add placeholder extension blueprints doc Signed-off-by: Patrik Oldsberg --- .../architecture/23-extension-blueprints.md | 11 +++++++++++ microsite/sidebars.json | 1 + 2 files changed, 12 insertions(+) create mode 100644 docs/frontend-system/architecture/23-extension-blueprints.md diff --git a/docs/frontend-system/architecture/23-extension-blueprints.md b/docs/frontend-system/architecture/23-extension-blueprints.md new file mode 100644 index 0000000000..046834c9db --- /dev/null +++ b/docs/frontend-system/architecture/23-extension-blueprints.md @@ -0,0 +1,11 @@ +--- +id: extension-blueprints +title: Frontend Extension Blueprints +sidebar_label: Extensions Blueprints +# prettier-ignore +description: Frontend extensions +--- + +> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.** + +TODO diff --git a/microsite/sidebars.json b/microsite/sidebars.json index be17d76e03..de7f39f0c0 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -454,6 +454,7 @@ "frontend-system/architecture/app", "frontend-system/architecture/plugins", "frontend-system/architecture/extensions", + "frontend-system/architecture/extension-blueprints", "frontend-system/architecture/extension-overrides", "frontend-system/architecture/references", "frontend-system/architecture/utility-apis", From d33c7d78901a25f1d28eb51ff53b8a915ea84522 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 14 Aug 2024 14:18:56 +0200 Subject: [PATCH 3/5] docs/frontend-system: initial extension blueprint docs with usage Signed-off-by: Patrik Oldsberg --- .../architecture/23-extension-blueprints.md | 53 ++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/docs/frontend-system/architecture/23-extension-blueprints.md b/docs/frontend-system/architecture/23-extension-blueprints.md index 046834c9db..43212d4a87 100644 --- a/docs/frontend-system/architecture/23-extension-blueprints.md +++ b/docs/frontend-system/architecture/23-extension-blueprints.md @@ -8,4 +8,55 @@ description: Frontend extensions > **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.** -TODO +The `createExtension` function and related APIs is considered a low-level building and fairly advanced building block, and is not typically what you would use when building plugins and features. Instead, the core APIs and plugins provide extension blueprints that makes it easier to create extensions for specific usages. These blueprints accept a number of parameters that is up to each blueprint to define, and then creates a new extension using the provided parameters. New blueprints are created using the `createExtensionBlueprint` function, and are by convention exported with the symbol `Blueprint`. If you are curious about what blueprints are available from a plugin or package, look for `*Blueprint` exports in the package's API, for plugins these are typically found in the `*-react` package. + +## Creating an extension from a blueprint + +Every extension blueprint provides a `make` method that can be used to create new extensions. It is a simple way to create a new extension where the base blueprint provides all the necessary functionality. All you need to do is to provide the necessary blueprint parameters, but you also have the ability to provide additional options, for example a `name` for the extension. + +The following is a simple example of how one might use the blueprint `make` method to create a new extension: + +```tsx +const myPageExtension = PageBlueprint.make({ + params: { + defaultPath: '/my-page', + loader: () => import('./components/MyPage').them(m => ), + }, +}); +``` + +The returned `myPageExtension` is an extension which is ready to be used in a plugin. It is the same type of object as is returned by the lower level `createExtension` function. + +## Creating an extension from a blueprint with overrides + +Every extension blueprint also provides a `makeWithOverrides` method. It is useful in cases where you want to provide additional integration points for an extension created with a blueprint. You might for example want to define additional inputs or configuration schema, or use the existing configuration to dynamically compute the parameters passed to the blueprint. + +The following is an example of how one might use the blueprint `makeWithOverrides` method to create a new extension: + +```tsx +const myPageExtension = PageBlueprint.makeWithOverrides({ + config: { + schema: { + layout: z => z.enum(['grid', 'rows']).default('grid'), + }, + }, + // The original blueprint factory is provided as the first argument + factory(originalFactory, { config }) { + // Call and forward the result from the original factory, providing + // the blueprint parameters as the first argument. + return originalFactory({ + defaultPath: '/my-page', + loader: () => + import('./components/MyPage').them(m => ( + // We can now access values from the factory context when providing + // the blueprint parameters, such as config values. + + )), + }); + }, +}); +``` + +When using `makeWithOverrides`, we no longer pass the blueprint parameters directly. Instead, we provide a `factory` function that receives the original blueprint factory as the first argument, and the extension factory context as the second. We can then call the original blueprint factory with the blueprint parameters and forward the result as the return value of out factory. Notice that when passing the blueprint parameters using this pattern we have access to a lot more information than when using the `make` method, at the cost of being more complex. + +Apart from the addition of the blueprint parameters of the first argument to the original factory function, the `makeWithOverrides` method works the same way as [extension overrides](./25-extension-overrides.md). All the same options and rules apply, including the ability to define additional inputs, override outputs, and so on. We therefore defer to the [extension overrides](./25-extension-overrides.md) documentation for more information on how to use the `makeWithOverrides` method. From 285e2b0b4bc138c3175162107bf1e3b5c1000941 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 14 Aug 2024 14:19:18 +0200 Subject: [PATCH 4/5] docs/frontend-system: remove extension creator docs Signed-off-by: Patrik Oldsberg --- .../architecture/20-extensions.md | 36 +++---------------- 1 file changed, 4 insertions(+), 32 deletions(-) diff --git a/docs/frontend-system/architecture/20-extensions.md b/docs/frontend-system/architecture/20-extensions.md index eec9947c97..d1024d5e17 100644 --- a/docs/frontend-system/architecture/20-extensions.md +++ b/docs/frontend-system/architecture/20-extensions.md @@ -293,38 +293,6 @@ app: title: 'Backstage' ``` -## Extension Creators - -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`. - -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. - -```tsx -export const HomeNavIcon = createNavItemExtension({ - routeRef: routeRefForTheHomePage, - title: 'Home', - icon: HomeIcon, -}); -``` - -### Extension Kind - -With the example `HomeNavIcon` will end up on the extension input `items` of the extensions with the id `app/nav`. It raises the question what the `id` of the `HomeNavIcon` itself is. The extension creator for the navigation item has a defined `kind`, which by convention matches the own name. So in this example `createNavItemExtension` sets the kind to `nav-item`. - -The `id` of the extension is then build out of `namespace`, `name` & `kind` like the following - where `namespace` & `name` are optional properties that can be passed to the extension creator: - -``` -id: kind:namespace/name -``` - -For more information on naming of extension refer to the [naming patterns documentation](./50-naming-patterns.md). - -### Extension Creators in libraries - -Extension creators should be exported from frontend library packages (e.g. `*-react`) rather than plugin packages. - -If an extension is only for in-house tweaks, it's okay to put it in the plugin package. But if you want other open source plugins to use it, or you already have a `-react` package, always put extension creators in the `-react` package. - ## Extension Boundary The `ExtensionBoundary` wraps extensions with several React contexts for different purposes @@ -370,3 +338,7 @@ export function createSomeExtension< }); } ``` + +### Extension Creators (Deprecated) + +Previous iterations of the frontend system used an "extension creator" pattern, where `createExtension` was wrapped up in a function for creating specific extension kinds. This pattern was similar to [blueprints](./23-extension-blueprints.md), but much harder to implement and maintain. It has been deprecated in favor of the new blueprints API. For example, `createPageExtension` was the extension creator equivalent of `PageBlueprint`. From 634a1202cd0088393553053b59f3590dec80a1af Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 14 Aug 2024 15:41:21 +0200 Subject: [PATCH 5/5] docs/frontend-system: initial docs for creating extension blueprints Signed-off-by: Patrik Oldsberg --- .../architecture/23-extension-blueprints.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/docs/frontend-system/architecture/23-extension-blueprints.md b/docs/frontend-system/architecture/23-extension-blueprints.md index 43212d4a87..ee09e7fec6 100644 --- a/docs/frontend-system/architecture/23-extension-blueprints.md +++ b/docs/frontend-system/architecture/23-extension-blueprints.md @@ -60,3 +60,83 @@ const myPageExtension = PageBlueprint.makeWithOverrides({ When using `makeWithOverrides`, we no longer pass the blueprint parameters directly. Instead, we provide a `factory` function that receives the original blueprint factory as the first argument, and the extension factory context as the second. We can then call the original blueprint factory with the blueprint parameters and forward the result as the return value of out factory. Notice that when passing the blueprint parameters using this pattern we have access to a lot more information than when using the `make` method, at the cost of being more complex. Apart from the addition of the blueprint parameters of the first argument to the original factory function, the `makeWithOverrides` method works the same way as [extension overrides](./25-extension-overrides.md). All the same options and rules apply, including the ability to define additional inputs, override outputs, and so on. We therefore defer to the [extension overrides](./25-extension-overrides.md) documentation for more information on how to use the `makeWithOverrides` method. + +## Creating an extension blueprint + +To create a new extension blueprint, you use the `createExtensionBlueprint` function. At the surface it is very similar to `createExtension`, but with a few key differences. Firstly you must provide a `kind` option, which will be the kind of all extensions created with the blueprint. See the [naming patterns section](./50-naming-patterns.md) for more information about how to select a good extension kind. Secondly, the `factory` function has a new signature where the first parameter is the blueprint parameters, and the second is the factory context. And finally, rather than returning an extension, `createExtensionBlueprint` returns a blueprint object with the `make` method and friends, which is used as is described above. + +The following is an example of how one might create a new extension blueprint: + +```tsx +export interface MyWidgetBlueprintParams { + defaultTitle: string; + element: JSX.Element; +} + +export const MyWidgetBlueprint = createExtensionBlueprint({ + kind: 'my-widget', + attachTo: { id: 'page:my-plugin', input: 'widgets' }, + config: { + schema: { + title: z.string().optional(), + }, + }, + output: [coreExtensionData.reactElement], + factory(params: MyWidgetBlueprintParams, { config }) { + return [ + // Note that while this is a valid pattern, you might often want to + // return separate pieces of data instead, more on that below. + coreExtensionData.reactElement( + + {params.element} + , + ), + ]; + }, +}); +``` + +This is of course a quite bare-bones example blueprint, but still a very real example. Blueprints can be very simple, there's already a lot of value in encapsulating the extension kind, attachment point, and output in a blueprint. + +Most of the options provided to `createExtensionBlueprint` can be overridden when using `makeWithOverrides` to create an extension from the blueprint. These overrides work the same way as [extension overrides](./25-extension-overrides.md), and we defer to that documentation for more information on how overrides work. + +### Blueprint-specific extension data references + +In some cases you may want to define and provide [extension data reference](./20-extensions.md#extension-data-references) that are specific to your blueprint. In the above example we might want to forward the `title` as data for example, rather than encapsulating it into the `MyWidgetContainer` component. This gives the parent extension more flexibility in the rendering for our example widget extensions. + +To do that, we create a new extension data reference for our widget title. This references is provided via the `dataRefs` options when we create the blueprint, which makes it available for use via `MyWidgetBlueprint.dataRefs.widgetTitle`. + +```tsx +export interface MyWidgetBlueprintParams { + defaultTitle: string; + element: JSX.Element; +} + +const widgetTitleRef = createExtensionDataRef().with({ + id: 'my-plugin.widget.title', +}); + +export const MyWidgetBlueprint = createExtensionBlueprint({ + kind: 'my-widget', + attachTo: { id: 'page:my-plugin', input: 'widgets' }, + config: { + schema: { + title: z.string().optional(), + }, + }, + output: [widgetTitleRef, coreExtensionData.reactElement], + factory(params: MyWidgetBlueprintParams, { config }) { + return [ + widgetTitleRef(config.title ?? params.defaultTitle), + coreExtensionData.reactElement(params.element), + ]; + }, + dataRefs: { + widgetTitle: widgetTitleRef, + }, +}); +``` + +### Extension Blueprints in libraries + +If you are publishing a plugin, the extension creators should always be exported from frontend library packages (e.g. `*-react`) rather than plugin packages.