Frontend System Migrations
NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.
Introduction
This section provides migration guides for different versions of the frontend system core APIs. Each guide will provide a summary of the changes that have been made for a particular Backstage release, and how to update your usage of the core APIs.
This guide is intended for app and plugin authors who have already migrated their code to the new frontend system, and are looking to keep it up to date with the latest changes. These guides do not cover trivial migrations that can be explained in a deprecation message, such as a renamed export.
1.31
namespace
parameter should be removed
The namespace
parameter to all createExtension
, createExtensionBlueprint
or any .make()
or .makeWithOverrides()
method can be removed. This will now default to the id
of the plugin
which should already be the case.
createExtensionOverrides
-> createFrontendModule
Extensions will need to be wrapped in a module in order to be installed in the frontend. This means that the createExtensionOverrides
function should be replaced with createFrontendModule
, and the pluginId
parameter should be set with the target pluginId
that you're overriding.
For example:
import {
createPageExtension,
createExtensionOverrides,
} from '@backstage/frontend-plugin-api';
const customSearchPage = PageBlueprint.make({
namespace: 'search',
params: {
defaultPath: '/search',
loader: () =>
import('./CustomSearchPage').then(m => <m.CustomSearchPage />),
},
});
export default createExtensionOverrides({
extensions: [customSearchPage],
});
Should now look like this:
import {
createPageExtension,
createFrontendModule,
} from '@backstage/frontend-plugin-api';
const customSearchPage = PageBlueprint.make({
params: {
defaultPath: '/search',
loader: () =>
import('./CustomSearchPage').then(m => <m.CustomSearchPage />),
},
});
export default createFrontendModule({
pluginId: 'search',
extensions: [customSearchPage],
});
Moved createApp
The createApp
function has been moved to the new @backstage/frontend-defaults
package. The old export from @backstage/frontend-app-api
is now deprecated and should be replaced with the new one.
Removed support for "v1" extensions
Extensions created with @backstage/frontend-plugin-api
from before the 1.30 release are no longer supported by createApp
. To be able to use extensions in a new app, they need to be created with @backstage/frontend-plugin-api
version 0.7.0 or later.
New type parameters for ExtensionDefinition
and ExtensionBlueprint
The type parameters of ExtensionDefinition
and ExtensionBlueprint
have been updated to use a single type parameter with an object, in order to make them easier to read and evolve.
Existing usage can generally be updated as follows:
ExtensionDefinition<any>
-> ExtensionDefinition
ExtensionDefinition<any, any>
-> ExtensionDefinition
ExtensionDefinition<TConfig>
-> ExtensionDefinition<{ config: TConfig }>
ExtensionDefinition<TConfig, TConfigInput>
-> ExtensionDefinition<{ config: TConfig, configInput: TConfigInput }>
If you need to infer the parameter you can use ExtensionDefinitionParameters
and ExtensionBlueprintParameters
, for example:
import {
ExtensionDefinition,
ExtensionDefinitionParameters,
} from '@backstage/frontend-plugin-api';
function myUtility<T extends ExtensionDefinitionParameters>(
ext: ExtensionDefinition<T>,
): T['config'] {
// ...
}
1.30
Reworked extension inputs and outputs
In previous versions of the frontend system you would define extension inputs and outputs as an "data map" where each named property corresponded to a piece of data that could be accessed via the same name in the extension factory. In order to better support extension overrides and blueprints, as well as reduce the risk of confusion, these data maps have been replaced by an array of data references.
For example, an extension previously declared like this:
createExtension({
name: 'example',
attachTo: { id: 'some-extension', input: 'content' },
inputs: {
header: createExtensionInput(
{ element: coreExtensionData.reactElement },
{
optional: true,
singleton: true,
},
),
},
output: { element: coreExtensionData.reactElement },
factory({ inputs }) {
return {
element: <ExtensionPage header={inputs.header?.output.element} />,
};
},
});
Would now look like this:
createExtension({
name: 'example',
attachTo: { id: 'some-extension', input: 'content' },
inputs: {
header: createExtensionInput([coreExtensionData.reactElement], {
optional: true,
singleton: true,
}),
},
output: [coreExtensionData.reactElement],
factory({ inputs }) {
return [
coreExtensionData.reactElement(
<ExtensionPage
header={inputs.header?.get(coreExtensionData.reactElement)}
/>,
),
];
},
});
Note the changes to the inputs
and output
declarations, as well as how these are used in the factory. Both the inputs
and output
now declare their expected data using an array, without names tied to each piece of data. The get
method on the input object is used to access the input data, and accept a data reference matching the data that was declared for that input.
The biggest change in practice is how the extension factories output their data. Instead of returning an object with the data values, you instead use each extension data reference to encapsulate a value and return a collection of these encapsulated values from the factory.
Blueprints instead of extension creators
The "extension creator" pattern where createExtension
was wrapped up in a function for creating specific kind of extensions has been replaced by extension blueprints. Extension creators were hard to implement and to maintain, with blueprints providing a much more consistent and powerful API surface for both plugin builders and integrators. For example, createPageExtension
was the extension creator equivalent of PageBlueprint
.
Replace all existing usages of extension creators in your plugin or app with the corresponding blueprint. For a given extension creator create<Kind>Extension
, the blueprint equivalent is <Kind>Blueprint
. There might be slight differences in the API between the two, but most often you just need to move the kind-specific options of the extension creator to be passed as parameters to the blueprint. Note that if your extension declared any additional inputs or config you'll need to use the .makeWithOverrides
method of the blueprint.
If your plugin exports and extension creators, these should be migrated to blueprints instead.
Extension tester rework
The createExtensionTester
from the @backstage/frontend-test-utils
package has been reworked to better support testing of extensions. The new API allows access to extension output directly using the new .get(ref)
method, and also provides access to all tested extensions through the new .query(id/extension)
method.
The .render()
method that used to render the test subject in a test app has been deprecated. The extension tester no longer constructs a full app tree, but instead only instantiates the tree for the extensions under test. If you want to test the rendering of an extension that outputs in an app, you can instead use the renderInTestApp
utility in combination with the new .reactElement()
method of the extension tester: renderInTestApp(tester.reactElement())
.
Extension data references update
The way that extension data references are declared has been changed to allow for type inference of the ID. This requires the declaration to be split into two separate function calls, one to supply the type and the other to infer any options. For example, a reference that was previously declared like this:
export const myExtension = createExtensionDataRef<MyType>('my-plugin.my-data');
Should be updated to the following:
export const myExtension = createExtensionDataRef<MyType>().with({
id: 'my-plugin.my-data',
});