From 691e73d8d6eafbf864bf1052fcb5a73adcf38610 Mon Sep 17 00:00:00 2001 From: blam Date: Mon, 9 Sep 2024 10:45:41 +0200 Subject: [PATCH] chore: update references from `createExtensionOverrides` to `createFrontendModule` instead Signed-off-by: blam --- .../architecture/25-extension-overrides.md | 17 ++- .../building-apps/08-migrating.md | 11 +- .../utility-apis/04-configuring.md | 7 +- plugins/api-docs/README-alpha.md | 115 ++++++++++-------- plugins/catalog-graph/README-alpha.md | 38 +++--- plugins/org/README-alpha.md | 38 +++--- 6 files changed, 120 insertions(+), 106 deletions(-) diff --git a/docs/frontend-system/architecture/25-extension-overrides.md b/docs/frontend-system/architecture/25-extension-overrides.md index 785843f6e0..a72eefdf9d 100644 --- a/docs/frontend-system/architecture/25-extension-overrides.md +++ b/docs/frontend-system/architecture/25-extension-overrides.md @@ -263,23 +263,19 @@ const overrideExtension = exampleExtension.override({ To install extension overrides in a Backstage app you should use `plugin.withOverrides` whenever you are overriding or adding extensions for a plugin. See the section on [overriding a plugin](./15-plugins.md#overriding-a-plugin) for more information. -There is also a `createExtensionOverrides` function that can be used to install a collection of standalone extensions in an app. This method will be replaced with a different mechanism in the future, but for now remains the only way to override the built-in extensions in the app or to package extensions for a plugin package separate from the plugin itself. - Note that while using either of these options you don't necessarily need to use the extension `.override(...)` method to create the overrides. You can also create new extensions with `createExtension` or a blueprint that are either completely net-new extensions, or override an existing extension by using the same `kind`, `namespace` and `name` to produce the same extension ID. -### Creating a standalone extension bundle +### Creating a frontend module -The following example shows how to create a standalone extension bundle that overrides the search page from the search plugin: +The following example shows how to create a frontend module that overrides the search page from the search plugin: ```tsx import { createPageExtension, - createExtensionOverrides, + createFrontendModule, } from '@backstage/frontend-plugin-api'; const customSearchPage = PageBlueprint.make({ - // Since this is a standalone extension we need to provide the namespace to match the search plugin - namespace: 'search', params: { defaultPath: '/search', loader: () => @@ -287,7 +283,8 @@ const customSearchPage = PageBlueprint.make({ }, }); -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'search', extensions: [customSearchPage], }); ``` @@ -296,11 +293,11 @@ Assuming the above code resides in the `@internal/search-page` package, you can ```tsx title="packages/app/src/App.tsx" import { createApp } from '@backstage/frontend-defaults'; -import searchPageOverride from '@internal/search-page'; +import searchPageModule from '@internal/search-page'; const app = createApp({ // highlight-next-line - features: [searchPageOverride], + features: [searchPageModule], }); export default app.createRoot(); diff --git a/docs/frontend-system/building-apps/08-migrating.md b/docs/frontend-system/building-apps/08-migrating.md index 96e7dd2bd5..3829078857 100644 --- a/docs/frontend-system/building-apps/08-migrating.md +++ b/docs/frontend-system/building-apps/08-migrating.md @@ -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 blueprint](../architecture/23-extension-blueprints.md) 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#creating-a-standalone-extension-bundle) section for more information. +Many of the `createApp` options have been migrated to use extensions instead. Each will have their own [extension blueprint](../architecture/23-extension-blueprints.md) that you use to create a custom extension. To add these standalone extensions to the app they need to be passed to `createFrontendModule`, which bundles them into a _feature_ that you can install in the app. See the [frontend module](../architecture/25-extension-overrides.md#creating-a-frontend-module) 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: @@ -103,7 +103,8 @@ For example, assuming you have a `lightTheme` extension that you want to add to const app = createApp({ features: [ // highlight-add-start - createExtensionOverrides({ + createFrontendModule({ + pluginId: 'app', extensions: [lightTheme], }), // highlight-add-end @@ -342,7 +343,8 @@ const exampleIconBundle = IconBundleBlueprint.make({ const app = createApp({ features: [ - createExtensionOverrides({ + createFrontendModule({ + pluginId: 'app', extensions: [exampleIconBundle], }), ], @@ -567,7 +569,8 @@ Here is an example converting the `CustomAppBarrier` into extension: createApp({ // ... features: [ - createExtensionOverrides({ + createFrontendModule({ + pluginId: 'app', extensions: [ AppRootWrapperBlueprint.make({ name: 'custom-app-barrier', diff --git a/docs/frontend-system/utility-apis/04-configuring.md b/docs/frontend-system/utility-apis/04-configuring.md index e403104506..4847fc6eaf 100644 --- a/docs/frontend-system/utility-apis/04-configuring.md +++ b/docs/frontend-system/utility-apis/04-configuring.md @@ -41,13 +41,14 @@ Like with other extension types, you replace Utility APIs with your own custom i ```tsx title="in your app" /* highlight-add-start */ -import { createExtensionOverrides } from '@backstage/frontend-plugin-api'; +import { createFrontendModule } from '@backstage/frontend-plugin-api'; class CustomWorkImpl implements WorkApi { /* ... */ } -const myOverrides = createExtensionOverrides({ +const workModule = createFrontendModule({ + pluginId: 'work', extensions: [ ApiBlueprint.make({ params: { @@ -66,7 +67,7 @@ export default createApp({ features: [ // ... other features /* highlight-add-next-line */ - myOverrides, + workModule, ], }); ``` diff --git a/plugins/api-docs/README-alpha.md b/plugins/api-docs/README-alpha.md index eb84ef8c27..2c8ab26ad7 100644 --- a/plugins/api-docs/README-alpha.md +++ b/plugins/api-docs/README-alpha.md @@ -203,21 +203,23 @@ The apis nav item icon can only be changed by overriding the extension, as the i Here is an example overriding the nav item extension with a custom icon component: ```tsx -import { createExtensionOverrides, createNavItemExtension } from '@backstage/backstage-plugin-api'; +import { + createFrontendModule, + createNavItemExtension, +} from '@backstage/backstage-plugin-api'; import { MyCustomApiDocsIcon } from './components'; -export default createExtensionOverrides( +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createNavItemExtension({ - // These namespace is necessary so the system knows that this extension will override the default nav item provided by the 'api-docs' plugin - namespace: 'api-docs', // It's your choice whether to use the original extension's title or a different one title: 'APIs', // Setting a custom icon component icon: MyCustomApiDocsIcon, - }) - ] -); + }), + ], +}); ``` For more information about where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides). @@ -273,24 +275,27 @@ The explorer page implementation can be [overridden](https://backstage.io/docs/f Here is an example overriding the APIs Explorer page component: ```tsx -import { createExtensionOverrides, createPageExtension } from '@backstage/backstage-plugin-api'; +import { + createFrontendModule, + createPageExtension, +} from '@backstage/backstage-plugin-api'; import { convertLegacyRouteRef } from '@backstage/core-compat-api'; -export default createExtensionOverrides( +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createPageExtension({ - // These namespace is necessary so the system knows that this extension will override the default explorer page provided by the 'api-docs' plugin - namespace: 'api-docs', // Ommitting name since we are overriding a plugin index page // It's up to you whether to use the original default path or not, but links that are hardcoded to the default path won't work if you change it defaultPath: '/api-docs', // Associating the page with a different route ref may result in the sidebar item or external plugin route pointing to an unreachable page routeRef: convertLegacyRouteRef(rootRoute), // Custom page components are loaded here - loader: () => import('./components').then(m => ) - }) - ] -); + loader: () => + import('./components').then(m => ), + }), + ], +}); ``` #### Apis Entities Cards @@ -356,14 +361,14 @@ app: Use extension overrides for completely re-implementing the has apis entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createEntityCardExtension({ - // These namespace and name necessary so the system knows that this extension will override the default 'has-apis' entity card extension provided by the 'api-docs' plugin - namespace: 'api-docs', + // Name is necessary so the system knows that this extension will override the default 'has-apis' entity card extension provided by the 'api-docs' plugin name: 'has-apis', // Returing a custom card component loader: () => @@ -429,14 +434,14 @@ app: Use extension overrides for completely re-implementing the has apis entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createEntityCardExtension({ - // These namespace and name necessary so the system knows that this extension will override the default 'definition' entity card extension provided by the 'api-docs' plugin - namespace: 'api-docs', + // Name is necessary so the system knows that this extension will override the default 'definition' entity card extension provided by the 'api-docs' plugin name: 'definition', // Returing a custom card component loader: () => @@ -502,14 +507,14 @@ app: Use extension overrides for completely re-implementing the has apis entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createEntityCardExtension({ - // These namespace and name necessary so the system knows that this extension will override the default 'provided-apis' entity card extension provided by the 'api-docs' plugin - namespace: 'api-docs', + // Name is necessary so the system knows that this extension will override the default 'provided-apis' entity card extension provided by the 'api-docs' plugin name: 'provided-apis', // Returing a custom card component loader: () => @@ -575,14 +580,14 @@ app: Use extension overrides for completely re-implementing the has apis entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createEntityCardExtension({ - // These namespace and name necessary so the system knows that this extension will override the default 'consumed-apis' entity card extension provided by the 'api-docs' plugin - namespace: 'api-docs', + // Name is necessary so the system knows that this extension will override the default 'consumed-apis' entity card extension provided by the 'api-docs' plugin name: 'consumed-apis', // Returing a custom card component loader: () => @@ -648,14 +653,14 @@ app: Use extension overrides for completely re-implementing the has apis entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createEntityCardExtension({ - // These namespace and name necessary so the system knows that this extension will override the default 'providing-components' entity card extension provided by the 'api-docs' plugin - namespace: 'api-docs', + // Name is necessary so the system knows that this extension will override the default 'providing-components' entity card extension provided by the 'api-docs' plugin name: 'providing-components', // Returing a custom card component loader: () => @@ -723,14 +728,15 @@ app: Use extension overrides for completely re-implementing the has apis entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', + pluginId: 'api-docs', extensions: [ createEntityCardExtension({ - // These namespace and name necessary so the system knows that this extension will override the default 'consuming-components' entity card extension provided by the 'api-docs' plugin - namespace: 'api-docs', + // Name is necessary so the system knows that this extension will override the default 'consuming-components' entity card extension provided by the 'api-docs' plugin name: 'consuming-components', // Returing a custom card component loader: () => @@ -812,14 +818,14 @@ app: Use extension overrides for completely re-implementing the has apis entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityContentExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createEntityContentExtension({ - // These namespace and name necessary so the system knows that this extension will override the default 'definition' entity content extension provided by the 'api-docs' plugin - namespace: 'api-docs', + // Name is necessary so the system knows that this extension will override the default 'definition' entity content extension provided by the 'api-docs' plugin name: 'definition', // Returing a custom content component loader: () => @@ -892,14 +898,14 @@ app: Use extension overrides for completely re-implementing the apis entity content extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityContentExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createEntityContentExtension({ - // These namespace and name necessary so the system knows that this extension will override the default 'apis' entity content extension provided by the 'api-docs' plugin - namespace: 'api-docs', + // Name is necessary so the system knows that this extension will override the default 'apis' entity content extension provided by the 'api-docs' plugin name: 'apis', // Returing a custom content component loader: () => @@ -929,7 +935,7 @@ This is an example with a made-up renderer for SQL schemas: ```tsx import { - createExtensionOverrides, + createFrontendModule, createApiExtenion, createApiFactory, } from '@backstage/frontend-plugin-api'; @@ -941,7 +947,8 @@ import { } from '@backstage/plugin-api-docs'; import { SqlRenderer } from '...'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createApiExtenion({ factory: createApiFactory({ @@ -982,7 +989,7 @@ Override the config api to configure a [`requestInterceptor` for Swagger UI](htt ```tsx import { - createExtensionOverrides, + createFrontendModule, createApiExtenion, createApiFactory, } from '@backstage/frontend-plugin-api'; @@ -993,7 +1000,8 @@ import { } from '@backstage/plugin-api-docs'; import { ApiEntity } from '@backstage/catalog-model'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createApiExtenion({ factory: createApiFactory({ @@ -1043,7 +1051,7 @@ If you want to limit the HTTP methods available for the `Try It Out` feature of ```tsx import { - createExtensionOverrides, + createFrontendModule, createApiExtenion, createApiFactory, } from '@backstage/frontend-plugin-api'; @@ -1054,7 +1062,8 @@ import { } from '@backstage/plugin-api-docs'; import { ApiEntity } from '@backstage/catalog-model'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'api-docs', extensions: [ createApiExtenion({ factory: createApiFactory({ diff --git a/plugins/catalog-graph/README-alpha.md b/plugins/catalog-graph/README-alpha.md index 784066c44f..06de696dcc 100644 --- a/plugins/catalog-graph/README-alpha.md +++ b/plugins/catalog-graph/README-alpha.md @@ -198,23 +198,28 @@ Overriding the card extension allows you to modify how it is implemented. Here is an example overriding the card extension with a custom component: ```tsx -import { createExtensionOverrides, createSchemaFromZod } from '@backstage/backstage-plugin-api'; +import { + createFrontendModule, + createSchemaFromZod, +} from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides( +export default createFrontendModule({ + pluginId: 'catalog-graph', extensions: [ createEntityCardExtension({ - // These namespace and name are necessary so the system knows that this extension will replace the default 'entity-relations' card extension provided by the 'catalog-graph' plugin - namespace: 'catalog-graph', name: 'entity-relations', - configSchema: createSchemaFromZod(z => z.object({ - filter: z.string().optional(), - // Ommitting the rest of default configs for simplicity in this example - })), - loader: () => import('./components').then(m => ) - }) - ] -); + configSchema: createSchemaFromZod(z => + z.object({ + filter: z.string().optional(), + // Ommitting the rest of default configs for simplicity in this example + }), + ), + loader: () => + import('./components').then(m => ), + }), + ], +}); ``` For more information about where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides). @@ -292,16 +297,15 @@ Overriding the page extension allows you to modify how it is implemented. Here is example overriding the page extension with a custom component: ```tsx -import { createExtensionOverrides, createPageExtension, createSchemaFromZod } from '@backstage/backstage-plugin-api'; +import { createFrontendModule, createPageExtension, createSchemaFromZod } from '@backstage/backstage-plugin-api'; import { convertLegacyRouteRef } from '@backstage/core-compat-api'; import { catalogGraphRouteRef } from '@backstage/plugin-catalog-graph'; -export default createExtensionOverrides( +export default createFrontendModule({ + pluginId: 'catalog-graph', extensions: [ createPageExtension({ // Ommiting name since it is an index page - // This namespace is necessary so the system knows that this extension will replace the default 'catalog-graph' page extension - namespace: 'catalog-graph', defaultPath: '/catalog-graph', routeRef: convertLegacyRouteRef(catalogGraphRouteRef), createSchemaFromZod(z => z.object({ @@ -311,7 +315,7 @@ export default createExtensionOverrides( loader: () => import('./components').then(m => ) }) ] -); +}); ``` For more information about where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides). diff --git a/plugins/org/README-alpha.md b/plugins/org/README-alpha.md index c8f9aee0d6..91aaa28167 100644 --- a/plugins/org/README-alpha.md +++ b/plugins/org/README-alpha.md @@ -119,14 +119,14 @@ app: Use extension overrides for completely re-implementing the group-profile entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'org', extensions: [ createEntityCardExtension({ - // These namespace and name are necessary so the system knows that this extension will override the default 'group-profile' entity card extension provided by the 'org' plugin - namespace: 'org', + // Name is necessary so the system knows that this extension will override the default 'group-profile' entity card extension provided by the 'org' plugin name: 'group-profile', // By default, this card will show up only for groups filter: 'kind:group' @@ -171,14 +171,14 @@ app: Use extension overrides for completely re-implementing the members-list entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'org', extensions: [ createEntityCardExtension({ - // These namespace and name are necessary so the system knows that this extension will override the default 'members-list' entity card extension provided by the 'org' plugin - namespace: 'org', + // Name is necessary so the system knows that this extension will override the default 'members-list' entity card extension provided by the 'org' plugin name: 'members-list', // By default, this card will show up only for groups filter: 'kind:group' @@ -223,14 +223,14 @@ app: Use extension overrides for completely re-implementing the ownership entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'org', extensions: [ createEntityCardExtension({ - // These namespace and name are necessary so the system knows that this extension will override the default 'ownership' entity card extension provided by the 'org' plugin - namespace: 'org', + // Name is necessary so the system knows that this extension will override the default 'ownership' entity card extension provided by the 'org' plugin name: 'ownership', // By default, this card will show up only for groups or users filter: 'kind:group,user' @@ -275,14 +275,14 @@ app: Use extension overrides for completely re-implementing the user-profile entity card extension: ```tsx -import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; +import { createFrontendModule } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'org', extensions: [ createEntityCardExtension({ - // These namespace and name are necessary so the system knows that this extension will override the default 'user-profile' entity card extension provided by the 'org' plugin - namespace: 'org', + // Name is necessary so the system knows that this extension will override the default 'user-profile' entity card extension provided by the 'org' plugin name: 'user-profile', // By default, this card will show up only for groups or users filter: 'kind:user' @@ -308,11 +308,11 @@ As the [NavItem](https://backstage.io/docs/reference/frontend-plugin-api.createn import { MyGroupsSidebarItem } from '@backstage/plugin-org'; import GroupIcon from '@material-ui/icons/People'; -export default createExtensionOverrides({ +export default createFrontendModule({ + pluginId: 'app', extensions: [ createExtension({ - // These namespace and name are necessary so the system knows that this extension will override the default app nav extension - namespace: 'app', + // Name is necessary so the system knows that this extension will override the default app nav extension name: 'nav', // Keeping the same attachment point as in the default App/Nav extension attachTo: { id: 'app/layout', input: 'nav' },