createExtensionBlueprint()

Home > @backstage/frontend-plugin-api > createExtensionBlueprint

Creates a new extension blueprint that encapsulates the creation of extensions of particular kinds.

Signature:

function createExtensionBlueprint<TParams extends object | ExtensionBlueprintDefineParams, UOutput extends ExtensionDataRef, TInputs extends {
    [inputName in string]: ExtensionInput<ExtensionDataRef, {
        optional: boolean;
        singleton: boolean;
    }>;
}, TConfigSchema extends {
    [key in string]: (zImpl: typeof z) => z.ZodType;
}, UFactoryOutput extends ExtensionDataValue<any, any>, TKind extends string, TDataRefs extends {
    [name in string]: ExtensionDataRef;
} = never>(options: CreateExtensionBlueprintOptions<TKind, TParams, UOutput, TInputs, TConfigSchema, UFactoryOutput, TDataRefs>): ExtensionBlueprint<{
    kind: TKind;
    params: TParams;
    output: UOutput extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? ExtensionDataRef<IData, IId, IConfig> : never;
    inputs: string extends keyof TInputs ? {} : TInputs;
    config: string extends keyof TConfigSchema ? {} : {
        [key in keyof TConfigSchema]: z.infer<ReturnType<TConfigSchema[key]>>;
    };
    configInput: string extends keyof TConfigSchema ? {} : z.input<z.ZodObject<{
        [key in keyof TConfigSchema]: ReturnType<TConfigSchema[key]>;
    }>>;
    dataRefs: TDataRefs;
}>;

Parameters

Parameter	Type	Description
options	CreateExtensionBlueprintOptions<TKind, TParams, UOutput, TInputs, TConfigSchema, UFactoryOutput, TDataRefs>

**Returns:**

ExtensionBlueprint<{ kind: TKind; params: TParams; output: UOutput extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? ExtensionDataRef<IData, IId, IConfig> : never; inputs: string extends keyof TInputs ? {} : TInputs; config: string extends keyof TConfigSchema ? {} : { [key in keyof TConfigSchema]: z.infer<ReturnType<TConfigSchema[key]>>; }; configInput: string extends keyof TConfigSchema ? {} : z.input<z.ZodObject<{ [key in keyof TConfigSchema]: ReturnType<TConfigSchema[key]>; }>>; dataRefs: TDataRefs; }>

Remarks

For details on how blueprints work, see the documentation for extension blueprints in the frontend system documentation.

Extension blueprints make it much easier for users to create new extensions for your plugin. Rather than letting them use createExtension() directly, you can define a set of parameters and default factory for your blueprint, removing a lot of the boilerplate and complexity that is otherwise needed to create an extension.

Each blueprint has its own kind that helps identify and group the extensions that have been created with it. For example the PageBlueprint has the kind 'page', and extensions created with it will be given the ID 'page:<plugin-id>[/<name>]'. Blueprints should always be exported as <PascalCaseKind>Blueprint.

When creating a blueprint the type of the parameters are inferred from the factory function that you provide. The exception to that is when you need your blueprint to include inferred type parameters, in which case you need to use the defineParams option. See the documentation for the defineParams option for more details on how that works.

Example

// In your plugin library
export const GreetingBlueprint = createExtensionBlueprint({
  kind: 'greeting',
  attachTo: { id: 'example', input: 'greetings' },
  output: [coreExtensionData.reactElement],
  factory(params: { greeting: string }) {
    return [coreExtensionData.reactElement(<h1>{params.greeting}</h1>)];
  },
});

// Someone using your blueprint in their plugin
const exampleGreeting = GreetingBlueprint.make({
  params: {
    greeting: 'Hello, world!',
  },
});