paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 24 Packages Projects Releases Wiki Activity

chore: update references from createExtensionOverrides to createFrontendModule instead

Browse Source 
Signed-off-by: blam <ben@blam.sh>
This commit is contained in:
blam
2024-09-09 10:45:41 +02:00
parent 5b43f7f78f
commit 691e73d8d6
6 changed files with 120 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/frontend-system/architecture/25-extension-overrides.md
+7 -10
View File
@@ -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();
docs/frontend-system/building-apps/08-migrating.md
+7 -4
View File
@@ -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',
docs/frontend-system/utility-apis/04-configuring.md
+4 -3
View File
@@ -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,
],
});
```
plugins/api-docs/README-alpha.md
+62 -53
View File
@@ -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 => <m.MyCustomApiExplorerPage />)
})
]
);
loader: () =>
import('./components').then(m => <m.MyCustomApiExplorerPage />),
}),
],
});
```
#### 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({
plugins/catalog-graph/README-alpha.md
+21 -17
View File
@@ -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 => <m.MyEntityRelationsCard />)
})
]
);
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 => <m.MyEntityRelationsCard />),
}),
],
});
```
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 => <m.CustomEntityRelationsPage />)
})
]
);
});
```
For more information about where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides).
plugins/org/README-alpha.md
+19 -19
View File
@@ -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' },