@backstage/frontend-plugin-api 0.14.2-next.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/CHANGELOG.md +144 -0
  2. package/dist/alpha.d.ts +6 -71
  3. package/dist/alpha.esm.js +4 -0
  4. package/dist/alpha.esm.js.map +1 -1
  5. package/dist/analytics/useAnalytics.esm.js +2 -0
  6. package/dist/analytics/useAnalytics.esm.js.map +1 -1
  7. package/dist/apis/definitions/AlertApi.esm.js +3 -2
  8. package/dist/apis/definitions/AlertApi.esm.js.map +1 -1
  9. package/dist/apis/definitions/AnalyticsApi.esm.js +3 -2
  10. package/dist/apis/definitions/AnalyticsApi.esm.js.map +1 -1
  11. package/dist/apis/definitions/AppLanguageApi.esm.js +3 -2
  12. package/dist/apis/definitions/AppLanguageApi.esm.js.map +1 -1
  13. package/dist/apis/definitions/AppThemeApi.esm.js +3 -2
  14. package/dist/apis/definitions/AppThemeApi.esm.js.map +1 -1
  15. package/dist/apis/definitions/AppTreeApi.esm.js +4 -1
  16. package/dist/apis/definitions/AppTreeApi.esm.js.map +1 -1
  17. package/dist/apis/definitions/ConfigApi.esm.js +3 -2
  18. package/dist/apis/definitions/ConfigApi.esm.js.map +1 -1
  19. package/dist/apis/definitions/DialogApi.esm.js +3 -2
  20. package/dist/apis/definitions/DialogApi.esm.js.map +1 -1
  21. package/dist/apis/definitions/DiscoveryApi.esm.js +3 -2
  22. package/dist/apis/definitions/DiscoveryApi.esm.js.map +1 -1
  23. package/dist/apis/definitions/ErrorApi.esm.js +3 -2
  24. package/dist/apis/definitions/ErrorApi.esm.js.map +1 -1
  25. package/dist/apis/definitions/FeatureFlagsApi.esm.js +3 -2
  26. package/dist/apis/definitions/FeatureFlagsApi.esm.js.map +1 -1
  27. package/dist/apis/definitions/FetchApi.esm.js +3 -2
  28. package/dist/apis/definitions/FetchApi.esm.js.map +1 -1
  29. package/dist/apis/definitions/IconsApi.esm.js +3 -2
  30. package/dist/apis/definitions/IconsApi.esm.js.map +1 -1
  31. package/dist/apis/definitions/IdentityApi.esm.js +3 -2
  32. package/dist/apis/definitions/IdentityApi.esm.js.map +1 -1
  33. package/dist/apis/definitions/OAuthRequestApi.esm.js +3 -2
  34. package/dist/apis/definitions/OAuthRequestApi.esm.js.map +1 -1
  35. package/dist/apis/definitions/PluginHeaderActionsApi.esm.js +3 -2
  36. package/dist/apis/definitions/PluginHeaderActionsApi.esm.js.map +1 -1
  37. package/dist/apis/definitions/PluginWrapperApi.esm.js +7 -3
  38. package/dist/apis/definitions/PluginWrapperApi.esm.js.map +1 -1
  39. package/dist/apis/definitions/RouteResolutionApi.esm.js +3 -2
  40. package/dist/apis/definitions/RouteResolutionApi.esm.js.map +1 -1
  41. package/dist/apis/definitions/StorageApi.esm.js +3 -2
  42. package/dist/apis/definitions/StorageApi.esm.js.map +1 -1
  43. package/dist/apis/definitions/SwappableComponentsApi.esm.js +3 -2
  44. package/dist/apis/definitions/SwappableComponentsApi.esm.js.map +1 -1
  45. package/dist/apis/definitions/ToastApi.esm.js +11 -0
  46. package/dist/apis/definitions/ToastApi.esm.js.map +1 -0
  47. package/dist/apis/definitions/TranslationApi.esm.js +3 -2
  48. package/dist/apis/definitions/TranslationApi.esm.js.map +1 -1
  49. package/dist/apis/definitions/auth.esm.js +33 -22
  50. package/dist/apis/definitions/auth.esm.js.map +1 -1
  51. package/dist/apis/system/ApiRef.esm.js +28 -20
  52. package/dist/apis/system/ApiRef.esm.js.map +1 -1
  53. package/dist/apis/system/useApi.esm.js +2 -1
  54. package/dist/apis/system/useApi.esm.js.map +1 -1
  55. package/dist/blueprints/AnalyticsImplementationBlueprint.esm.js +1 -1
  56. package/dist/blueprints/AnalyticsImplementationBlueprint.esm.js.map +1 -1
  57. package/dist/blueprints/ApiBlueprint.esm.js +1 -1
  58. package/dist/blueprints/AppRootElementBlueprint.esm.js +1 -1
  59. package/dist/blueprints/NavItemBlueprint.esm.js +1 -1
  60. package/dist/blueprints/NavItemBlueprint.esm.js.map +1 -1
  61. package/dist/blueprints/PageBlueprint.esm.js +17 -6
  62. package/dist/blueprints/PageBlueprint.esm.js.map +1 -1
  63. package/dist/blueprints/PluginHeaderActionBlueprint.esm.js +3 -1
  64. package/dist/blueprints/PluginHeaderActionBlueprint.esm.js.map +1 -1
  65. package/dist/blueprints/PluginWrapperBlueprint.esm.js +4 -2
  66. package/dist/blueprints/PluginWrapperBlueprint.esm.js.map +1 -1
  67. package/dist/blueprints/SubPageBlueprint.esm.js +3 -1
  68. package/dist/blueprints/SubPageBlueprint.esm.js.map +1 -1
  69. package/dist/components/ExtensionBoundary.esm.js +3 -2
  70. package/dist/components/ExtensionBoundary.esm.js.map +1 -1
  71. package/dist/components/PageLayout.esm.js.map +1 -1
  72. package/dist/components/createSwappableComponent.esm.js +2 -0
  73. package/dist/components/createSwappableComponent.esm.js.map +1 -1
  74. package/dist/frontend-internal/src/apis/OpaqueApiRef.esm.js +9 -0
  75. package/dist/frontend-internal/src/apis/OpaqueApiRef.esm.js.map +1 -0
  76. package/dist/frontend-internal/src/wiring/InternalExtensionDefinition.esm.js.map +1 -1
  77. package/dist/frontend-internal/src/wiring/InternalFrontendPlugin.esm.js.map +1 -1
  78. package/dist/index.d.ts +380 -1457
  79. package/dist/index.esm.js +3 -0
  80. package/dist/index.esm.js.map +1 -1
  81. package/dist/routing/useRouteRef.esm.js +2 -0
  82. package/dist/routing/useRouteRef.esm.js.map +1 -1
  83. package/dist/schema/createSchemaFromZod.esm.js +1 -1
  84. package/dist/schema/createSchemaFromZod.esm.js.map +1 -1
  85. package/dist/translation/useTranslationRef.esm.js +2 -0
  86. package/dist/translation/useTranslationRef.esm.js.map +1 -1
  87. package/dist/types/alpha.d-DzeiOzxk.d.ts +1425 -0
  88. package/dist/wiring/createExtension.esm.js +6 -0
  89. package/dist/wiring/createExtension.esm.js.map +1 -1
  90. package/dist/wiring/createExtensionBlueprint.esm.js +2 -0
  91. package/dist/wiring/createExtensionBlueprint.esm.js.map +1 -1
  92. package/dist/wiring/createExtensionDataRef.esm.js.map +1 -1
  93. package/dist/wiring/createFrontendModule.esm.js +1 -0
  94. package/dist/wiring/createFrontendModule.esm.js.map +1 -1
  95. package/dist/wiring/createFrontendPlugin.esm.js +6 -0
  96. package/dist/wiring/createFrontendPlugin.esm.js.map +1 -1
  97. package/dist/wiring/resolveExtensionDefinition.esm.js.map +1 -1
  98. package/dist/wiring/resolveInputOverrides.esm.js.map +1 -1
  99. package/package.json +11 -10
package/dist/index.d.ts CHANGED
@@ -2,9 +2,12 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
2
2
  import * as react from 'react';
3
3
  import { ReactNode, JSX as JSX$1, ComponentType, PropsWithChildren } from 'react';
4
4
  import * as _backstage_frontend_plugin_api from '@backstage/frontend-plugin-api';
5
- import { Expand, JsonObject, Observable, JsonValue, ExpandRecursive } from '@backstage/types';
6
- import { z } from 'zod';
5
+ import { I as IconElement, R as RouteRef, A as AnyRouteRefParams, S as SubRouteRef, E as ExternalRouteRef, F as FrontendFeature, a as IconComponent, b as AppNode, c as FrontendPlugin, d as ApiRef, e as ApiHolder, T as TypesToApiRefs, f as ApiFactory, g as AnyApiFactory } from './types/alpha.d-DzeiOzxk.js';
6
+ export { n as AnyApiRef, i as AppNodeEdges, j as AppNodeInstance, k as AppNodeSpec, l as AppTree, m as AppTreeApi, J as ConfigurableExtensionDataRef, a1 as CreateExtensionBlueprintOptions, C as CreateExtensionOptions, X as CreateFrontendModuleOptions, L as CreateFrontendPluginOptions, Y as Extension, Z as ExtensionAttachTo, a2 as ExtensionBlueprint, a5 as ExtensionBlueprintDefineParams, a3 as ExtensionBlueprintParameters, a4 as ExtensionBlueprintParams, _ as ExtensionDataContainer, G as ExtensionDataRef, H as ExtensionDataValue, w as ExtensionDefinition, x as ExtensionDefinitionAttachTo, y as ExtensionDefinitionParameters, a0 as ExtensionFactoryMiddleware, B as ExtensionInput, $ as FeatureFlagConfig, W as FrontendModule, Q as FrontendPluginInfo, U as FrontendPluginInfoOptions, O as OverridableExtensionDefinition, M as OverridableFrontendPlugin, N as PluginOptions, P as PluginWrapperApi, o as PluginWrapperBlueprint, q as PluginWrapperDefinition, u as PortableSchema, h as appTreeApiRef, v as createExtension, a6 as createExtensionBlueprint, a7 as createExtensionBlueprintParams, D as createExtensionDataRef, z as createExtensionInput, t as createExternalRouteRef, V as createFrontendModule, K as createFrontendPlugin, r as createRouteRef, s as createSubRouteRef, p as pluginWrapperApiRef } from './types/alpha.d-DzeiOzxk.js';
7
+ import { Observable, JsonValue, Expand, ExpandRecursive } from '@backstage/types';
7
8
  import { Config } from '@backstage/config';
9
+ import '@backstage/filter-predicates';
10
+ import 'zod/v3';
8
11
 
9
12
  /**
10
13
  * Analytics context envelope.
@@ -39,1433 +42,54 @@ declare const AnalyticsContext: (options: {
39
42
  children: ReactNode;
40
43
  }) => react_jsx_runtime.JSX.Element;
41
44
 
42
- /**
43
- * IconComponent is the common icon type used throughout Backstage when
44
- * working with and rendering generic icons, including the app system icons.
45
- *
46
- * @remarks
47
- *
48
- * The type is based on SvgIcon from Material UI, but we do not want the plugin-api
49
- * package to have a dependency on Material UI, nor do we want the props to be as broad
50
- * as the SvgIconProps interface.
51
- *
52
- * If you have the need to forward additional props from SvgIconProps, you can
53
- * open an issue or submit a PR to the main Backstage repo. When doing so please
54
- * also describe your use-case and reasoning of the addition.
55
- *
56
- * @public
57
- * @deprecated Use {@link IconElement} instead, passing `<MyIcon />` rather than `MyIcon`.
58
- */
59
- type IconComponent = ComponentType<{
60
- fontSize?: 'medium' | 'large' | 'small' | 'inherit';
61
- }>;
62
- /**
63
- * The type used for icon elements throughout Backstage.
64
- *
65
- * @remarks
66
- *
67
- * Icons should be exactly 24x24 pixels in size.
68
- *
69
- * @public
70
- */
71
- type IconElement = JSX$1.Element | null;
72
-
73
- /**
74
- * Catch-all type for route params.
75
- *
76
- * @public
77
- */
78
- type AnyRouteRefParams = {
79
- [param in string]: string;
80
- } | undefined;
81
-
82
- /**
83
- * Absolute route reference.
84
- *
85
- * @remarks
86
- *
87
- * See {@link https://backstage.io/docs/plugins/composability#routing-system}.
88
- *
89
- * @public
90
- */
91
- interface RouteRef<TParams extends AnyRouteRefParams = AnyRouteRefParams> {
92
- readonly $$type: '@backstage/RouteRef';
93
- readonly T: TParams;
94
- }
95
- /**
96
- * Create a {@link RouteRef} from a route descriptor.
97
- *
98
- * @param config - Description of the route reference to be created.
99
- * @public
100
- */
101
- declare function createRouteRef<TParams extends {
102
- [param in TParamKeys]: string;
103
- } | undefined = undefined, TParamKeys extends string = string>(config?: {
104
- /** A list of parameter names that the path that this route ref is bound to must contain */
105
- readonly params?: string extends TParamKeys ? (keyof TParams)[] : TParamKeys[];
106
- aliasFor?: string;
107
- }): RouteRef<keyof TParams extends never ? undefined : string extends TParamKeys ? TParams : {
108
- [param in TParamKeys]: string;
109
- }>;
110
-
111
- /** @public */
112
- declare const coreExtensionData: {
113
- title: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<string, "core.title", {}>;
114
- /** An icon element for the extension. Should be exactly 24x24 pixels. */
115
- icon: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<IconElement, "core.icon", {}>;
116
- reactElement: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<JSX$1.Element, "core.reactElement", {}>;
117
- routePath: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<string, "core.routing.path", {}>;
118
- routeRef: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<RouteRef<_backstage_frontend_plugin_api.AnyRouteRefParams>, "core.routing.ref", {}>;
119
- };
120
-
121
- /** @public */
122
- type ExtensionDataValue<TData, TId extends string> = {
123
- readonly $$type: '@backstage/ExtensionDataValue';
124
- readonly id: TId;
125
- readonly value: TData;
126
- };
127
- /** @public */
128
- type ExtensionDataRef<TData = unknown, TId extends string = string, TConfig extends {
129
- optional?: true;
130
- } = {
131
- optional?: true;
132
- }> = {
133
- readonly $$type: '@backstage/ExtensionDataRef';
134
- readonly id: TId;
135
- readonly T: TData;
136
- readonly config: TConfig;
137
- };
138
- /** @public */
139
- type ExtensionDataRefToValue<TDataRef extends AnyExtensionDataRef> = TDataRef extends ExtensionDataRef<infer IData, infer IId, any> ? ExtensionDataValue<IData, IId> : never;
140
- /**
141
- * @deprecated Use `ExtensionDataRef` without type parameters instead.
142
- * @public
143
- */
144
- type AnyExtensionDataRef = ExtensionDataRef;
145
- /** @public */
146
- interface ConfigurableExtensionDataRef<TData, TId extends string, TConfig extends {
147
- optional?: true;
148
- } = {}> extends ExtensionDataRef<TData, TId, TConfig> {
149
- optional(): ConfigurableExtensionDataRef<TData, TId, TConfig & {
150
- optional: true;
151
- }>;
152
- (t: TData): ExtensionDataValue<TData, TId>;
153
- }
154
- /** @public */
155
- declare function createExtensionDataRef<TData>(): {
156
- with<TId extends string>(options: {
157
- id: TId;
158
- }): ConfigurableExtensionDataRef<TData, TId>;
159
- };
160
-
161
- /** @public */
162
- interface ExtensionInput<UExtensionData extends ExtensionDataRef<unknown, string, {
163
- optional?: true;
164
- }> = ExtensionDataRef, TConfig extends {
165
- singleton: boolean;
166
- optional: boolean;
167
- internal?: boolean;
168
- } = {
169
- singleton: boolean;
170
- optional: boolean;
171
- internal?: boolean;
172
- }> {
173
- readonly $$type: '@backstage/ExtensionInput';
174
- readonly extensionData: Array<UExtensionData>;
175
- readonly config: TConfig;
176
- readonly replaces?: Array<{
177
- id: string;
178
- input: string;
179
- }>;
180
- }
181
- /**
182
- * Creates a new extension input to be passed to the input map of an extension.
183
- *
184
- * @remarks
185
- *
186
- * Extension inputs created with this function can be passed to any `inputs` map
187
- * as part of creating or overriding an extension.
188
- *
189
- * The array of extension data references defines the data this input expects.
190
- * If the required data is not provided by the attached extension, the
191
- * attachment will fail.
192
- *
193
- * The `config` object can be used to restrict the behavior and shape of the
194
- * input. By default an input will accept zero or more extensions from any
195
- * plugin. The following options are available:
196
- *
197
- * - `singleton`: If set to `true`, only one extension can be attached to the
198
- * input at a time. Additional extensions will trigger an app error and be
199
- * ignored.
200
- * - `optional`: If set to `true`, the input is optional and can be omitted,
201
- * this only has an effect if the `singleton` is set to `true`.
202
- * - `internal`: If set to `true`, only extensions from the same plugin will be
203
- * allowed to attach to this input. Other extensions will trigger an app error
204
- * and be ignored.
205
- *
206
- * @param extensionData - The array of extension data references that this input
207
- * expects.
208
- * @param config - The configuration object for the input.
209
- * @returns An extension input declaration.
210
- * @example
211
- * ```ts
212
- * const extension = createExtension({
213
- * attachTo: { id: 'example-parent', input: 'example-input' },
214
- * inputs: {
215
- * content: createExtensionInput([coreExtensionData.reactElement], {
216
- * singleton: true,
217
- * }),
218
- * },
219
- * output: [coreExtensionData.reactElement],
220
- * *factory({ inputs }) {
221
- * const content = inputs.content?.get(coreExtensionData.reactElement);
222
- * yield coreExtensionData.reactElement(<ContentWrapper>{content}</ContentWrapper>);
223
- * },
224
- * });
225
- * ```
226
- * @public
227
- */
228
- declare function createExtensionInput<UExtensionData extends ExtensionDataRef<unknown, string, {
229
- optional?: true;
230
- }>, TConfig extends {
231
- singleton?: boolean;
232
- optional?: boolean;
233
- internal?: boolean;
234
- }>(extensionData: Array<UExtensionData>, config?: TConfig & {
235
- replaces?: Array<{
236
- id: string;
237
- input: string;
238
- }>;
239
- }): ExtensionInput<UExtensionData, {
240
- singleton: TConfig['singleton'] extends true ? true : false;
241
- optional: TConfig['optional'] extends true ? true : false;
242
- internal: TConfig['internal'] extends true ? true : false;
243
- }>;
244
-
245
- /** @ignore */
246
- type ResolvedInputValueOverrides<TInputs extends {
247
- [inputName in string]: ExtensionInput;
248
- } = {
249
- [inputName in string]: ExtensionInput;
250
- }> = Expand<{
251
- [KName in keyof TInputs as TInputs[KName] extends ExtensionInput<any, {
252
- optional: infer IOptional extends boolean;
253
- singleton: boolean;
254
- internal?: boolean;
255
- }> ? IOptional extends true ? never : KName : never]: TInputs[KName] extends ExtensionInput<infer IDataRefs, {
256
- optional: boolean;
257
- singleton: infer ISingleton extends boolean;
258
- internal?: boolean;
259
- }> ? ISingleton extends true ? Iterable<ExtensionDataRefToValue<IDataRefs>> : Array<Iterable<ExtensionDataRefToValue<IDataRefs>>> : never;
260
- } & {
261
- [KName in keyof TInputs as TInputs[KName] extends ExtensionInput<any, {
262
- optional: infer IOptional extends boolean;
263
- singleton: boolean;
264
- internal?: boolean;
265
- }> ? IOptional extends true ? KName : never : never]?: TInputs[KName] extends ExtensionInput<infer IDataRefs, {
266
- optional: boolean;
267
- singleton: infer ISingleton extends boolean;
268
- internal?: boolean;
269
- }> ? ISingleton extends true ? Iterable<ExtensionDataRefToValue<IDataRefs>> : Array<Iterable<ExtensionDataRefToValue<IDataRefs>>> : never;
270
- }>;
271
-
272
- /** @public */
273
- interface CreateFrontendModuleOptions<TPluginId extends string, TExtensions extends readonly ExtensionDefinition[]> {
274
- pluginId: TPluginId;
275
- extensions?: TExtensions;
276
- featureFlags?: FeatureFlagConfig[];
277
- }
278
- /** @public */
279
- interface FrontendModule {
280
- readonly $$type: '@backstage/FrontendModule';
281
- readonly pluginId: string;
282
- }
283
- /**
284
- * Creates a new module that can be installed in a Backstage app.
285
- *
286
- * @remarks
287
- *
288
- * Modules are used to add or override extensions for an existing plugin. If a
289
- * module provides an extension with the same ID as one provided by the plugin,
290
- * the extension provided by the module will always take precedence.
291
- *
292
- * Every module is created for a specific plugin by providing the
293
- * unique ID of the plugin that the module should be installed for. If that
294
- * plugin is not present in the app, the module will be ignored and have no
295
- * effect.
296
- *
297
- * For more information on how modules work, see the
298
- * {@link https://backstage.io/docs/frontend-system/architecture/extension-overrides#creating-a-frontend-module | documentation for modules}
299
- * in the frontend system documentation.
300
- *
301
- * It is recommended to name the module variable of the form `<pluginId>Module<ModuleName>`.
302
- *
303
- * @example
304
- *
305
- * ```tsx
306
- * import { createFrontendModule } from '@backstage/frontend-plugin-api';
307
- *
308
- * export const exampleModuleCustomPage = createFrontendModule({
309
- * pluginId: 'example',
310
- * extensions: [
311
- * // Overrides the default page for the 'example' plugin
312
- * PageBlueprint.make({
313
- * path: '/example',
314
- * loader: () => import('./CustomPage').then(m => <m.CustomPage />),
315
- * }),
316
- * ],
317
- * });
318
- * ```
319
- *
320
- * @public
321
- */
322
- declare function createFrontendModule<TId extends string, TExtensions extends readonly ExtensionDefinition[]>(options: CreateFrontendModuleOptions<TId, TExtensions>): FrontendModule;
323
-
324
- /** @public */
325
- type PortableSchema<TOutput, TInput = TOutput> = {
326
- parse: (input: TInput) => TOutput;
327
- schema: JsonObject;
328
- };
329
-
330
- /** @public */
331
- type ExtensionAttachTo = {
332
- id: string;
333
- input: string;
334
- } | Array<{
335
- id: string;
336
- input: string;
337
- }>;
338
- /**
339
- * @deprecated Use {@link ExtensionAttachTo} instead.
340
- * @public
341
- */
342
- type ExtensionAttachToSpec = ExtensionAttachTo;
343
- /** @public */
344
- interface Extension<TConfig, TConfigInput = TConfig> {
345
- $$type: '@backstage/Extension';
346
- readonly id: string;
347
- readonly attachTo: ExtensionAttachToSpec;
348
- readonly disabled: boolean;
349
- readonly configSchema?: PortableSchema<TConfig, TConfigInput>;
350
- }
351
- /** @ignore */
352
- type ResolveExtensionId<TExtension extends ExtensionDefinition, TNamespace extends string> = TExtension extends ExtensionDefinition<{
353
- kind: infer IKind extends string | undefined;
354
- name: infer IName extends string | undefined;
355
- params: any;
356
- }> ? [string] extends [IKind | IName] ? never : (undefined extends IName ? TNamespace : `${TNamespace}/${IName}`) extends infer INamePart extends string ? IKind extends string ? `${IKind}:${INamePart}` : INamePart : never : never;
357
-
358
- type CompareChars<A extends string, B extends string> = [A, B] extends [
359
- `${infer IAHead}${infer IARest}`,
360
- `${infer IBHead}${infer IBRest}`
361
- ] ? IAHead extends IBHead ? IBRest extends '' ? IARest extends '' ? 'eq' : 'gt' : IARest extends '' ? 'lt' : CompareChars<IARest, IBRest> : `0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz` extends `${string}${IAHead}${string}${IBHead}${string}` ? 'lt' : 'gt' : 'eq';
362
- type CompareStrings<A extends string | undefined, B extends string | undefined> = A extends B ? 'eq' : A extends undefined ? 'lt' : B extends undefined ? 'gt' : CompareChars<A & string, B & string>;
363
- type CompareExtensions<A extends ExtensionDefinition, B extends ExtensionDefinition> = CompareStrings<A['T']['kind'], B['T']['kind']> extends 'eq' ? CompareStrings<A['T']['name'], B['T']['name']> : CompareStrings<A['T']['kind'], B['T']['kind']>;
364
- type SortExtensionsInner<TPivot extends ExtensionDefinition, TRest extends readonly ExtensionDefinition[], TLow extends readonly ExtensionDefinition[], THigh extends readonly ExtensionDefinition[]> = TRest extends [
365
- infer IHead extends ExtensionDefinition,
366
- ...infer IRest extends readonly ExtensionDefinition[]
367
- ] ? CompareExtensions<IHead, TPivot> extends 'lt' ? SortExtensionsInner<TPivot, IRest, [...TLow, IHead], THigh> : SortExtensionsInner<TPivot, IRest, TLow, [...THigh, IHead]> : [low: TLow, high: THigh];
368
- type SortExtensions<T extends readonly ExtensionDefinition[]> = T extends [
369
- infer IPivot extends ExtensionDefinition,
370
- ...infer IRest extends readonly ExtensionDefinition[]
371
- ] ? SortExtensionsInner<IPivot, IRest, [], []> extends [
372
- low: infer ILow extends readonly ExtensionDefinition[],
373
- high: infer IHigh extends readonly ExtensionDefinition[]
374
- ] ? [...SortExtensions<ILow>, IPivot, ...SortExtensions<IHigh>] : 'invalid SortExtensionsInner' : [];
375
- type UnionToIntersection$1<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
376
- type PopUnion$1<U> = UnionToIntersection$1<U extends any ? () => U : never> extends () => infer R ? [next: R, rest: Exclude<U, R>] : undefined;
377
- type UnionToArray<U, T = U, TResult extends T[] = []> = PopUnion$1<U> extends [
378
- next: infer INext extends T,
379
- rest: infer IRest extends T
380
- ] ? UnionToArray<IRest, T, [INext, ...TResult]> : TResult;
381
- type ExtensionArrayToMap<T extends ExtensionDefinition[], TId extends string, TOut extends {
382
- [KId in string]: ExtensionDefinition;
383
- } = {}> = T extends [
384
- infer IHead extends ExtensionDefinition,
385
- ...infer IRest extends ExtensionDefinition[]
386
- ] ? ExtensionArrayToMap<IRest, TId, TOut & {
387
- [K in ResolveExtensionId<IHead, TId>]: IHead;
388
- }> : TOut extends infer O ? {
389
- [K in keyof O]: O[K];
390
- } : never;
391
- /** @ignore */
392
- type MakeSortedExtensionsMap<UExtensions extends ExtensionDefinition, TId extends string> = ExtensionArrayToMap<SortExtensions<UnionToArray<UExtensions>>, TId>;
393
-
394
- /**
395
- * Descriptor of a route relative to an absolute {@link RouteRef}.
396
- *
397
- * @remarks
398
- *
399
- * See {@link https://backstage.io/docs/plugins/composability#routing-system}.
400
- *
401
- * @public
402
- */
403
- interface SubRouteRef<TParams extends AnyRouteRefParams = AnyRouteRefParams> {
404
- readonly $$type: '@backstage/SubRouteRef';
405
- readonly T: TParams;
406
- readonly path: string;
407
- }
408
- /**
409
- * Used in {@link PathParams} type declaration.
410
- * @ignore
411
- */
412
- type ParamPart<S extends string> = S extends `:${infer Param}` ? Param : never;
413
- /**
414
- * Used in {@link PathParams} type declaration.
415
- * @ignore
416
- */
417
- type ParamNames<S extends string> = S extends `${infer Part}/${infer Rest}` ? ParamPart<Part> | ParamNames<Rest> : ParamPart<S>;
418
- /**
419
- * This utility type helps us infer a Param object type from a string path
420
- * For example, `/foo/:bar/:baz` inferred to `{ bar: string, baz: string }`
421
- * @ignore
422
- */
423
- type PathParams<S extends string> = {
424
- [name in ParamNames<S>]: string;
425
- };
426
- /**
427
- * Merges a param object type with an optional params type into a params object.
428
- * @ignore
429
- */
430
- type MergeParams<P1 extends {
431
- [param in string]: string;
432
- }, P2 extends AnyRouteRefParams> = (P1[keyof P1] extends never ? {} : P1) & (P2 extends undefined ? {} : P2);
433
- /**
434
- * Convert empty params to undefined.
435
- * @ignore
436
- */
437
- type TrimEmptyParams<Params extends {
438
- [param in string]: string;
439
- }> = keyof Params extends never ? undefined : Params;
440
- /**
441
- * Creates a SubRouteRef type given the desired parameters and parent route parameters.
442
- * The parameters types are merged together while ensuring that there is no overlap between the two.
443
- *
444
- * @ignore
445
- */
446
- type MakeSubRouteRef<Params extends {
447
- [param in string]: string;
448
- }, ParentParams extends AnyRouteRefParams> = keyof Params & keyof ParentParams extends never ? SubRouteRef<TrimEmptyParams<MergeParams<Params, ParentParams>>> : never;
449
- /**
450
- * Create a {@link SubRouteRef} from a route descriptor.
451
- *
452
- * @param config - Description of the route reference to be created.
453
- * @public
454
- */
455
- declare function createSubRouteRef<Path extends string, ParentParams extends AnyRouteRefParams = never>(config: {
456
- path: Path;
457
- parent: RouteRef<ParentParams>;
458
- }): MakeSubRouteRef<PathParams<Path>, ParentParams>;
459
-
460
- /**
461
- * Route descriptor, to be later bound to a concrete route by the app. Used to implement cross-plugin route references.
462
- *
463
- * @remarks
464
- *
465
- * See {@link https://backstage.io/docs/plugins/composability#routing-system}.
466
- *
467
- * @public
468
- */
469
- interface ExternalRouteRef<TParams extends AnyRouteRefParams = AnyRouteRefParams> {
470
- readonly $$type: '@backstage/ExternalRouteRef';
471
- readonly T: TParams;
472
- }
473
- /**
474
- * Creates a route descriptor, to be later bound to a concrete route by the app. Used to implement cross-plugin route references.
475
- *
476
- * @remarks
477
- *
478
- * See {@link https://backstage.io/docs/plugins/composability#routing-system}.
479
- *
480
- * @param options - Description of the route reference to be created.
481
- * @public
482
- */
483
- declare function createExternalRouteRef<TParams extends {
484
- [param in TParamKeys]: string;
485
- } | undefined = undefined, TParamKeys extends string = string>(config?: {
486
- /**
487
- * The parameters that will be provided to the external route reference.
488
- */
489
- readonly params?: string extends TParamKeys ? (keyof TParams)[] : TParamKeys[];
490
- /**
491
- * The route (typically in another plugin) that this should map to by default.
492
- *
493
- * The string is expected to be on the standard `<plugin id>.<route id>` form,
494
- * for example `techdocs.docRoot`.
495
- */
496
- defaultTarget?: string;
497
- }): ExternalRouteRef<keyof TParams extends never ? undefined : string extends TParamKeys ? TParams : {
498
- [param in TParamKeys]: string;
499
- }>;
500
-
501
- /**
502
- * React hook for constructing URLs to routes.
503
- *
504
- * @remarks
505
- *
506
- * See {@link https://backstage.io/docs/plugins/composability#routing-system}
507
- *
508
- * @param routeRef - The ref to route that should be converted to URL.
509
- * @returns A function that will in turn return the concrete URL of the `routeRef`, or `undefined` if the route is not available.
510
- * @public
511
- */
512
- declare function useRouteRef<TParams extends AnyRouteRefParams>(routeRef: RouteRef<TParams> | SubRouteRef<TParams> | ExternalRouteRef<TParams>): RouteFunc<TParams> | undefined;
513
-
514
- /**
515
- * React hook for retrieving dynamic params from the current URL.
516
- * @param _routeRef - Ref of the current route.
517
- * @public
518
- */
519
- declare function useRouteRefParams<Params extends AnyRouteRefParams>(_routeRef: RouteRef<Params> | SubRouteRef<Params>): Params;
520
-
521
- /**
522
- * Information about the plugin.
523
- *
524
- * @public
525
- * @remarks
526
- *
527
- * This interface is intended to be extended via [module
528
- * augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation)
529
- * in order to add fields that are specific to each project.
530
- *
531
- * For example, one might add a `slackChannel` field that is read from the
532
- * opaque manifest file.
533
- *
534
- * See the options for `createApp` for more information about how to
535
- * customize the parsing of manifest files.
536
- */
537
- interface FrontendPluginInfo {
538
- /**
539
- * The name of the package that implements the plugin.
540
- */
541
- packageName?: string;
542
- /**
543
- * The version of the plugin, typically the version of the package.json file.
544
- */
545
- version?: string;
546
- /**
547
- * As short description of the plugin, typically the description field in
548
- * package.json.
549
- */
550
- description?: string;
551
- /**
552
- * The owner entity references of the plugin.
553
- */
554
- ownerEntityRefs?: string[];
555
- /**
556
- * Links related to the plugin.
557
- */
558
- links?: Array<{
559
- title: string;
560
- url: string;
561
- }>;
562
- }
563
- /**
564
- * Options for providing information for a plugin.
565
- *
566
- * @public
567
- */
568
- type FrontendPluginInfoOptions = {
569
- /**
570
- * A loader function for the package.json file for the plugin.
571
- */
572
- packageJson?: () => Promise<{
573
- name: string;
574
- } & JsonObject>;
575
- /**
576
- * A loader function for an opaque manifest file for the plugin.
577
- */
578
- manifest?: () => Promise<JsonObject>;
579
- };
580
- /**
581
- * A variant of the {@link FrontendPlugin} interface that can also be used to install overrides for the plugin.
582
- *
583
- * @public
584
- */
585
- interface OverridableFrontendPlugin<TRoutes extends {
586
- [name in string]: RouteRef | SubRouteRef;
587
- } = {
588
- [name in string]: RouteRef | SubRouteRef;
589
- }, TExternalRoutes extends {
590
- [name in string]: ExternalRouteRef;
591
- } = {
592
- [name in string]: ExternalRouteRef;
593
- }, TExtensionMap extends {
594
- [id in string]: ExtensionDefinition;
595
- } = {
596
- [id in string]: ExtensionDefinition;
597
- }> extends FrontendPlugin<TRoutes, TExternalRoutes> {
598
- getExtension<TId extends keyof TExtensionMap>(id: TId): OverridableExtensionDefinition<TExtensionMap[TId]['T']>;
599
- withOverrides(options: {
600
- extensions?: Array<ExtensionDefinition>;
601
- /**
602
- * Overrides the display title of the plugin.
603
- */
604
- title?: string;
605
- /**
606
- * Overrides the display icon of the plugin.
607
- */
608
- icon?: IconElement;
609
- /**
610
- * Overrides the original info loaders of the plugin one by one.
611
- */
612
- info?: FrontendPluginInfoOptions;
613
- }): OverridableFrontendPlugin<TRoutes, TExternalRoutes, TExtensionMap>;
614
- }
615
- /** @public */
616
- interface FrontendPlugin<TRoutes extends {
617
- [name in string]: RouteRef | SubRouteRef;
618
- } = {
619
- [name in string]: RouteRef | SubRouteRef;
620
- }, TExternalRoutes extends {
621
- [name in string]: ExternalRouteRef;
622
- } = {
623
- [name in string]: ExternalRouteRef;
624
- }> {
625
- readonly $$type: '@backstage/FrontendPlugin';
626
- /**
627
- * The plugin ID.
628
- */
629
- readonly pluginId: string;
630
- /**
631
- * Deprecated alias for `pluginId`.
632
- *
633
- * @deprecated Use `pluginId` instead.
634
- */
635
- readonly id: string;
636
- /**
637
- * The display title of the plugin, used in page headers and navigation.
638
- * Falls back to the plugin ID if not provided.
639
- */
640
- readonly title?: string;
641
- /**
642
- * The display icon of the plugin, used in page headers and navigation.
643
- */
644
- readonly icon?: IconElement;
645
- readonly routes: TRoutes;
646
- readonly externalRoutes: TExternalRoutes;
647
- /**
648
- * Loads the plugin info.
649
- */
650
- info(): Promise<FrontendPluginInfo>;
651
- }
652
- /** @public */
653
- interface PluginOptions<TId extends string, TRoutes extends {
654
- [name in string]: RouteRef | SubRouteRef;
655
- }, TExternalRoutes extends {
656
- [name in string]: ExternalRouteRef;
657
- }, TExtensions extends readonly ExtensionDefinition[]> {
658
- pluginId: TId;
659
- /**
660
- * The display title of the plugin, used in page headers and navigation.
661
- * Falls back to the plugin ID if not provided.
662
- */
663
- title?: string;
664
- /**
665
- * The display icon of the plugin, used in page headers and navigation.
666
- */
667
- icon?: IconElement;
668
- routes?: TRoutes;
669
- externalRoutes?: TExternalRoutes;
670
- extensions?: TExtensions;
671
- featureFlags?: FeatureFlagConfig[];
672
- info?: FrontendPluginInfoOptions;
673
- }
674
- /**
675
- * Creates a new plugin that can be installed in a Backstage app.
676
- *
677
- * @remarks
678
- *
679
- * Every plugin is created with a unique ID and a set of extensions
680
- * that are installed as part of the plugin.
681
- *
682
- * For more information on how plugins work, see the
683
- * {@link https://backstage.io/docs/frontend-system/building-plugins/index | documentation for plugins}
684
- * in the frontend system documentation.
685
- *
686
- * @example
687
- *
688
- * ```tsx
689
- * import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
690
- *
691
- * export const examplePlugin = createFrontendPlugin({
692
- * pluginId: 'example',
693
- * extensions: [
694
- * PageBlueprint.make({
695
- * path: '/example',
696
- * loader: () => import('./ExamplePage').then(m => <m.ExamplePage />),
697
- * }),
698
- * ],
699
- * });
700
- * ```
701
- *
702
- * @public
703
- */
704
- declare function createFrontendPlugin<TId extends string, TExtensions extends readonly ExtensionDefinition[], TRoutes extends {
705
- [name in string]: RouteRef | SubRouteRef;
706
- } = {}, TExternalRoutes extends {
707
- [name in string]: ExternalRouteRef;
708
- } = {}>(options: PluginOptions<TId, TRoutes, TExternalRoutes, TExtensions>): OverridableFrontendPlugin<TRoutes, TExternalRoutes, MakeSortedExtensionsMap<TExtensions[number], TId>>;
709
-
710
- /**
711
- * Feature flag configuration.
712
- *
713
- * @public
714
- */
715
- type FeatureFlagConfig = {
716
- /** Feature flag name */
717
- name: string;
718
- };
719
- /** @public */
720
- type ExtensionDataContainer<UExtensionData extends ExtensionDataRef> = Iterable<UExtensionData extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? IConfig['optional'] extends true ? never : ExtensionDataValue<IData, IId> : never> & {
721
- get<TId extends UExtensionData['id']>(ref: ExtensionDataRef<any, TId, any>): UExtensionData extends ExtensionDataRef<infer IData, TId, infer IConfig> ? IConfig['optional'] extends true ? IData | undefined : IData : never;
722
- };
723
- /** @public */
724
- type ExtensionFactoryMiddleware = (originalFactory: (contextOverrides?: {
725
- config?: JsonObject;
726
- }) => ExtensionDataContainer<ExtensionDataRef>, context: {
727
- node: AppNode;
728
- apis: ApiHolder;
729
- config?: JsonObject;
730
- }) => Iterable<ExtensionDataValue<any, any>>;
731
- /** @public */
732
- type FrontendFeature = (Omit<FrontendPlugin, 'pluginId'> & {
733
- pluginId?: string;
734
- }) | FrontendModule;
735
-
736
- /**
737
- * A function used to define a parameter mapping function in order to facilitate
738
- * advanced parameter typing for extension blueprints.
739
- *
740
- * @remarks
741
- *
742
- * This function is primarily intended to enable the use of inferred type
743
- * parameters for blueprint params, but it can also be used to transoform the
744
- * params before they are handed ot the blueprint.
745
- *
746
- * The function must return an object created with
747
- * {@link createExtensionBlueprintParams}.
748
- *
749
- * @public
750
- */
751
- type ExtensionBlueprintDefineParams<TParams extends object = object, TInput = any> = (params: TInput) => ExtensionBlueprintParams<TParams>;
752
- /**
753
- * An opaque type that represents a set of parameters to be passed to a blueprint.
754
- *
755
- * @remarks
756
- *
757
- * Created with {@link createExtensionBlueprintParams}.
758
- *
759
- * @public
760
- */
761
- type ExtensionBlueprintParams<T extends object = object> = {
762
- $$type: '@backstage/BlueprintParams';
763
- T: T;
764
- };
765
- /**
766
- * Wraps a plain blueprint parameter object in an opaque {@link ExtensionBlueprintParams} object.
767
- *
768
- * This is used in the definition of the `defineParams` option of {@link ExtensionBlueprint}.
769
- *
770
- * @public
771
- * @param params - The plain blueprint parameter object to wrap.
772
- * @returns The wrapped blueprint parameter object.
773
- */
774
- declare function createExtensionBlueprintParams<T extends object = object>(params: T): ExtensionBlueprintParams<T>;
775
- /**
776
- * @public
777
- */
778
- type CreateExtensionBlueprintOptions<TKind extends string, TParams extends object | ExtensionBlueprintDefineParams, UOutput extends ExtensionDataRef, TInputs extends {
779
- [inputName in string]: ExtensionInput;
780
- }, TConfigSchema extends {
781
- [key in string]: (zImpl: typeof z) => z.ZodType;
782
- }, UFactoryOutput extends ExtensionDataValue<any, any>, TDataRefs extends {
783
- [name in string]: ExtensionDataRef;
784
- }, UParentInputs extends ExtensionDataRef> = {
785
- kind: TKind;
786
- attachTo: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<UOutput, UParentInputs>;
787
- disabled?: boolean;
788
- inputs?: TInputs;
789
- output: Array<UOutput>;
790
- config?: {
791
- schema: TConfigSchema;
792
- };
793
- /**
794
- * This option is used to further refine the blueprint params. When this
795
- * option is used, the blueprint will require params to be passed in callback
796
- * form. This function can both transform the params before they are handed to
797
- * the blueprint factory, but importantly it also allows you to define
798
- * inferred type parameters for your blueprint params.
799
- *
800
- * @example
801
- * Blueprint definition with inferred type parameters:
802
- * ```ts
803
- * const ExampleBlueprint = createExtensionBlueprint({
804
- * kind: 'example',
805
- * attachTo: { id: 'example', input: 'example' },
806
- * output: [exampleComponentDataRef, exampleFetcherDataRef],
807
- * defineParams<T>(params: {
808
- * component(props: ExampleProps<T>): JSX.Element | null
809
- * fetcher(options: FetchOptions): Promise<FetchResult<T>>
810
- * }) {
811
- * return createExtensionBlueprintParams(params);
812
- * },
813
- * *factory(params) {
814
- * yield exampleComponentDataRef(params.component)
815
- * yield exampleFetcherDataRef(params.fetcher)
816
- * },
817
- * });
818
- * ```
819
- *
820
- * @example
821
- * Usage of the above example blueprint:
822
- * ```ts
823
- * const example = ExampleBlueprint.make({
824
- * params: defineParams => defineParams({
825
- * component: ...,
826
- * fetcher: ...,
827
- * }),
828
- * });
829
- * ```
830
- */
831
- defineParams?: TParams extends ExtensionBlueprintDefineParams ? TParams : 'The defineParams option must be a function if provided, see the docs for details';
832
- factory(params: TParams extends ExtensionBlueprintDefineParams ? ReturnType<TParams>['T'] : TParams, context: {
833
- node: AppNode;
834
- apis: ApiHolder;
835
- config: {
836
- [key in keyof TConfigSchema]: z.infer<ReturnType<TConfigSchema[key]>>;
837
- };
838
- inputs: Expand<ResolvedExtensionInputs<TInputs>>;
839
- }): Iterable<UFactoryOutput>;
840
- dataRefs?: TDataRefs;
841
- } & VerifyExtensionFactoryOutput<UOutput, UFactoryOutput>;
842
- /** @public */
843
- type ExtensionBlueprintParameters = {
844
- kind: string;
845
- params?: object | ExtensionBlueprintDefineParams;
846
- configInput?: {
847
- [K in string]: any;
848
- };
849
- config?: {
850
- [K in string]: any;
851
- };
852
- output?: ExtensionDataRef;
853
- inputs?: {
854
- [KName in string]: ExtensionInput;
855
- };
856
- dataRefs?: {
857
- [name in string]: ExtensionDataRef;
858
- };
859
- };
860
- /** @ignore */
861
- type ParamsFactory<TDefiner extends ExtensionBlueprintDefineParams> = (defineParams: TDefiner) => ReturnType<TDefiner>;
862
- /**
863
- * Represents any form of params input that can be passed to a blueprint.
864
- * This also includes the invalid form of passing a plain params object to a blueprint that uses a definition callback.
865
- *
866
- * @ignore
867
- */
868
- type AnyParamsInput$1<TParams extends object | ExtensionBlueprintDefineParams> = TParams extends ExtensionBlueprintDefineParams<infer IParams> ? IParams | ParamsFactory<TParams> : TParams | ParamsFactory<ExtensionBlueprintDefineParams<TParams, TParams>>;
869
- /**
870
- * @public
871
- */
872
- interface ExtensionBlueprint<T extends ExtensionBlueprintParameters = ExtensionBlueprintParameters> {
873
- dataRefs: T['dataRefs'];
874
- make<TName extends string | undefined, TParamsInput extends AnyParamsInput$1<NonNullable<T['params']>>, UParentInputs extends ExtensionDataRef>(args: {
875
- name?: TName;
876
- attachTo?: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<NonNullable<T['output']>, UParentInputs>;
877
- disabled?: boolean;
878
- params: TParamsInput extends ExtensionBlueprintDefineParams ? TParamsInput : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `<blueprint>.make({ params: defineParams => defineParams(<params>) })`' : T['params'];
879
- }): OverridableExtensionDefinition<{
880
- kind: T['kind'];
881
- name: string | undefined extends TName ? undefined : TName;
882
- config: T['config'];
883
- configInput: T['configInput'];
884
- output: T['output'];
885
- inputs: T['inputs'];
886
- params: T['params'];
887
- }>;
888
- /**
889
- * Creates a new extension from the blueprint.
890
- *
891
- * You must either pass `params` directly, or define a `factory` that can
892
- * optionally call the original factory with the same params.
893
- */
894
- makeWithOverrides<TName extends string | undefined, TExtensionConfigSchema extends {
895
- [key in string]: (zImpl: typeof z) => z.ZodType;
896
- }, UFactoryOutput extends ExtensionDataValue<any, any>, UNewOutput extends ExtensionDataRef, UParentInputs extends ExtensionDataRef, TExtraInputs extends {
897
- [inputName in string]: ExtensionInput;
898
- } = {}>(args: {
899
- name?: TName;
900
- attachTo?: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UParentInputs>;
901
- disabled?: boolean;
902
- inputs?: TExtraInputs & {
903
- [KName in keyof T['inputs']]?: `Error: Input '${KName & string}' is already defined in parent definition`;
904
- };
905
- output?: Array<UNewOutput>;
906
- config?: {
907
- schema: TExtensionConfigSchema & {
908
- [KName in keyof T['config']]?: `Error: Config key '${KName & string}' is already defined in parent schema`;
909
- };
910
- };
911
- factory(originalFactory: <TParamsInput extends AnyParamsInput$1<NonNullable<T['params']>>>(params: TParamsInput extends ExtensionBlueprintDefineParams ? TParamsInput : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(defineParams => defineParams(<params>))`' : T['params'], context?: {
912
- config?: T['config'];
913
- inputs?: ResolvedInputValueOverrides<NonNullable<T['inputs']>>;
914
- }) => ExtensionDataContainer<NonNullable<T['output']>>, context: {
915
- node: AppNode;
916
- apis: ApiHolder;
917
- config: T['config'] & {
918
- [key in keyof TExtensionConfigSchema]: z.infer<ReturnType<TExtensionConfigSchema[key]>>;
919
- };
920
- inputs: Expand<ResolvedExtensionInputs<T['inputs'] & TExtraInputs>>;
921
- }): Iterable<UFactoryOutput> & VerifyExtensionFactoryOutput<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UFactoryOutput>;
922
- }): OverridableExtensionDefinition<{
923
- config: Expand<(string extends keyof TExtensionConfigSchema ? {} : {
924
- [key in keyof TExtensionConfigSchema]: z.infer<ReturnType<TExtensionConfigSchema[key]>>;
925
- }) & T['config']>;
926
- configInput: Expand<(string extends keyof TExtensionConfigSchema ? {} : z.input<z.ZodObject<{
927
- [key in keyof TExtensionConfigSchema]: ReturnType<TExtensionConfigSchema[key]>;
928
- }>>) & T['configInput']>;
929
- output: ExtensionDataRef extends UNewOutput ? T['output'] : UNewOutput;
930
- inputs: Expand<T['inputs'] & TExtraInputs>;
931
- kind: T['kind'];
932
- name: string | undefined extends TName ? undefined : TName;
933
- params: T['params'];
934
- }>;
935
- }
936
- /**
937
- * Creates a new extension blueprint that encapsulates the creation of
938
- * extensions of particular kinds.
939
- *
940
- * @remarks
941
- *
942
- * For details on how blueprints work, see the
943
- * {@link https://backstage.io/docs/frontend-system/architecture/extension-blueprints | documentation for extension blueprints}
944
- * in the frontend system documentation.
945
- *
946
- * Extension blueprints make it much easier for users to create new extensions
947
- * for your plugin. Rather than letting them use {@link createExtension}
948
- * directly, you can define a set of parameters and default factory for your
949
- * blueprint, removing a lot of the boilerplate and complexity that is otherwise
950
- * needed to create an extension.
951
- *
952
- * Each blueprint has its own `kind` that helps identify and group the
953
- * extensions that have been created with it. For example the
954
- * {@link PageBlueprint} has the kind `'page'`, and extensions created with it
955
- * will be given the ID `'page:<plugin-id>[/<name>]'`. Blueprints should always
956
- * be exported as `<PascalCaseKind>Blueprint`.
957
- *
958
- * When creating a blueprint the type of the parameters are inferred from the
959
- * `factory` function that you provide. The exception to that is when you need
960
- * your blueprint to include inferred type parameters, in which case you need to
961
- * use the `defineParams` option. See the documentation for the `defineParams`
962
- * option for more details on how that works.
963
- *
964
- * @example
965
- * ```tsx
966
- * // In your plugin library
967
- * export const GreetingBlueprint = createExtensionBlueprint({
968
- * kind: 'greeting',
969
- * attachTo: { id: 'example', input: 'greetings' },
970
- * output: [coreExtensionData.reactElement],
971
- * factory(params: { greeting: string }) {
972
- * return [coreExtensionData.reactElement(<h1>{params.greeting}</h1>)];
973
- * },
974
- * });
975
- *
976
- * // Someone using your blueprint in their plugin
977
- * const exampleGreeting = GreetingBlueprint.make({
978
- * params: {
979
- * greeting: 'Hello, world!',
980
- * },
981
- * });
982
- * ```
983
- * @public
984
- */
985
- declare function createExtensionBlueprint<TParams extends object | ExtensionBlueprintDefineParams, UOutput extends ExtensionDataRef, TInputs extends {
986
- [inputName in string]: ExtensionInput;
987
- }, TConfigSchema extends {
988
- [key in string]: (zImpl: typeof z) => z.ZodType;
989
- }, UFactoryOutput extends ExtensionDataValue<any, any>, TKind extends string, UParentInputs extends ExtensionDataRef, TDataRefs extends {
990
- [name in string]: ExtensionDataRef;
991
- } = never>(options: CreateExtensionBlueprintOptions<TKind, TParams, UOutput, TInputs, TConfigSchema, UFactoryOutput, TDataRefs, UParentInputs>): ExtensionBlueprint<{
992
- kind: TKind;
993
- params: TParams;
994
- output: UOutput extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? ExtensionDataRef<IData, IId, IConfig> : never;
995
- inputs: string extends keyof TInputs ? {} : TInputs;
996
- config: string extends keyof TConfigSchema ? {} : {
997
- [key in keyof TConfigSchema]: z.infer<ReturnType<TConfigSchema[key]>>;
998
- };
999
- configInput: string extends keyof TConfigSchema ? {} : z.input<z.ZodObject<{
1000
- [key in keyof TConfigSchema]: ReturnType<TConfigSchema[key]>;
1001
- }>>;
1002
- dataRefs: TDataRefs;
1003
- }>;
1004
-
1005
- /**
1006
- * Convert a single extension input into a matching resolved input.
1007
- * @public
1008
- */
1009
- type ResolvedExtensionInput<TExtensionInput extends ExtensionInput> = TExtensionInput['extensionData'] extends Array<ExtensionDataRef> ? {
1010
- node: AppNode;
1011
- } & ExtensionDataContainer<TExtensionInput['extensionData'][number]> : never;
1012
- /**
1013
- * Converts an extension input map into a matching collection of resolved inputs.
1014
- * @public
1015
- */
1016
- type ResolvedExtensionInputs<TInputs extends {
1017
- [name in string]: ExtensionInput;
1018
- }> = {
1019
- [InputName in keyof TInputs]: false extends TInputs[InputName]['config']['singleton'] ? Array<Expand<ResolvedExtensionInput<TInputs[InputName]>>> : false extends TInputs[InputName]['config']['optional'] ? Expand<ResolvedExtensionInput<TInputs[InputName]>> : Expand<ResolvedExtensionInput<TInputs[InputName]> | undefined>;
1020
- };
1021
- type ToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
1022
- type PopUnion<U> = ToIntersection<U extends any ? () => U : never> extends () => infer R ? [rest: Exclude<U, R>, next: R] : undefined;
1023
- /** @ignore */
1024
- type JoinStringUnion<U, TDiv extends string = ', ', TResult extends string = ''> = PopUnion<U> extends [infer IRest extends string, infer INext extends string] ? TResult extends '' ? JoinStringUnion<IRest, TDiv, INext> : JoinStringUnion<IRest, TDiv, `${TResult}${TDiv}${INext}`> : TResult;
1025
- /** @ignore */
1026
- type RequiredExtensionIds<UExtensionData extends ExtensionDataRef> = UExtensionData extends any ? UExtensionData['config']['optional'] extends true ? never : UExtensionData['id'] : never;
1027
- /** @ignore */
1028
- type VerifyExtensionFactoryOutput<UDeclaredOutput extends ExtensionDataRef, UFactoryOutput extends ExtensionDataValue<any, any>> = [RequiredExtensionIds<UDeclaredOutput>] extends [UFactoryOutput['id']] ? [UFactoryOutput['id']] extends [UDeclaredOutput['id']] ? {} : `Error: The extension factory has undeclared output(s): ${JoinStringUnion<Exclude<UFactoryOutput['id'], UDeclaredOutput['id']>>}` : `Error: The extension factory is missing the following output(s): ${JoinStringUnion<Exclude<RequiredExtensionIds<UDeclaredOutput>, UFactoryOutput['id']>>}`;
1029
- /** @ignore */
1030
- type VerifyExtensionAttachTo<UOutput extends ExtensionDataRef, UParentInput extends ExtensionDataRef> = ExtensionDataRef extends UParentInput ? {} : [RequiredExtensionIds<UParentInput>] extends [RequiredExtensionIds<UOutput>] ? {} : `Error: This parent extension input requires the following extension data, but it is not declared as guaranteed output of this extension: ${JoinStringUnion<Exclude<RequiredExtensionIds<UParentInput>, RequiredExtensionIds<UOutput>>>}`;
1031
- /**
1032
- * Specifies where an extension should attach in the extension tree.
1033
- *
1034
- * @remarks
1035
- *
1036
- * A standard attachment point declaration will specify the ID of the parent extension, as well as the name of the input to attach to.
1037
- *
1038
- * There are two more advanced forms that are available for more complex use-cases:
1039
- *
1040
- * 1. Relative attachment points: using the `relative` property instead of `id`, the attachment point is resolved relative to the current plugin.
1041
- * 2. Extension input references: using a reference in code to another extension's input in the same plugin. These references are always relative.
1042
- *
1043
- * @example
1044
- * ```ts
1045
- * // Attach to a specific extension by full ID
1046
- * { id: 'app/routes', input: 'routes' }
1047
- *
1048
- * // Attach to an extension in the same plugin by kind
1049
- * { relative: { kind: 'page' }, input: 'actions' }
1050
- *
1051
- * // Attach to a specific input of another extension
1052
- * const page = ParentBlueprint.make({ ... });
1053
- * const child = ChildBlueprint.make({ attachTo: page.inputs.children });
1054
- * ```
1055
- *
1056
- * @public
1057
- */
1058
- type ExtensionDefinitionAttachTo<UParentInputs extends ExtensionDataRef = ExtensionDataRef> = {
1059
- id: string;
1060
- input: string;
1061
- relative?: never;
1062
- } | {
1063
- relative: {
1064
- kind?: string;
1065
- name?: string;
1066
- };
1067
- input: string;
1068
- id?: never;
1069
- } | ExtensionInput<UParentInputs>;
1070
- /** @public */
1071
- type CreateExtensionOptions<TKind extends string | undefined, TName extends string | undefined, UOutput extends ExtensionDataRef, TInputs extends {
1072
- [inputName in string]: ExtensionInput;
1073
- }, TConfigSchema extends {
1074
- [key: string]: (zImpl: typeof z) => z.ZodType;
1075
- }, UFactoryOutput extends ExtensionDataValue<any, any>, UParentInputs extends ExtensionDataRef> = {
1076
- kind?: TKind;
1077
- name?: TName;
1078
- attachTo: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<UOutput, UParentInputs>;
1079
- disabled?: boolean;
1080
- inputs?: TInputs;
1081
- output: Array<UOutput>;
1082
- config?: {
1083
- schema: TConfigSchema;
1084
- };
1085
- factory(context: {
1086
- node: AppNode;
1087
- apis: ApiHolder;
1088
- config: {
1089
- [key in keyof TConfigSchema]: z.infer<ReturnType<TConfigSchema[key]>>;
1090
- };
1091
- inputs: Expand<ResolvedExtensionInputs<TInputs>>;
1092
- }): Iterable<UFactoryOutput>;
1093
- } & VerifyExtensionFactoryOutput<UOutput, UFactoryOutput>;
1094
- /** @public */
1095
- type ExtensionDefinitionParameters = {
1096
- kind?: string;
1097
- name?: string;
1098
- configInput?: {
1099
- [K in string]: any;
1100
- };
1101
- config?: {
1102
- [K in string]: any;
1103
- };
1104
- output?: ExtensionDataRef;
1105
- inputs?: {
1106
- [KName in string]: ExtensionInput;
1107
- };
1108
- params?: object | ExtensionBlueprintDefineParams;
1109
- };
1110
- /**
1111
- * Same as the one in `createExtensionBlueprint`, but with `ParamsFactory` inlined.
1112
- * It can't be exported because it breaks API reports.
1113
- * @ignore
1114
- */
1115
- type AnyParamsInput<TParams extends object | ExtensionBlueprintDefineParams> = TParams extends ExtensionBlueprintDefineParams<infer IParams> ? IParams | ((define: TParams) => ReturnType<TParams>) : TParams | ((define: ExtensionBlueprintDefineParams<TParams, TParams>) => ReturnType<ExtensionBlueprintDefineParams<TParams, TParams>>);
1116
- /** @public */
1117
- interface ExtensionDefinition<TParams extends ExtensionDefinitionParameters = ExtensionDefinitionParameters> {
1118
- $$type: '@backstage/ExtensionDefinition';
1119
- readonly T: TParams;
1120
- }
1121
- /** @public */
1122
- interface OverridableExtensionDefinition<T extends ExtensionDefinitionParameters = ExtensionDefinitionParameters> extends ExtensionDefinition<T> {
1123
- /**
1124
- * References to the inputs of this extension, which can be used to attach child extensions.
1125
- */
1126
- readonly inputs: {
1127
- [K in keyof T['inputs']]: ExtensionInput<T['inputs'][K] extends ExtensionInput<infer IData> ? IData : never>;
1128
- };
1129
- override<TExtensionConfigSchema extends {
1130
- [key in string]: (zImpl: typeof z) => z.ZodType;
1131
- }, UFactoryOutput extends ExtensionDataValue<any, any>, UNewOutput extends ExtensionDataRef, TExtraInputs extends {
1132
- [inputName in string]: ExtensionInput;
1133
- }, TParamsInput extends AnyParamsInput<NonNullable<T['params']>>, UParentInputs extends ExtensionDataRef>(args: Expand<{
1134
- attachTo?: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UParentInputs>;
1135
- disabled?: boolean;
1136
- inputs?: TExtraInputs & {
1137
- [KName in keyof T['inputs']]?: `Error: Input '${KName & string}' is already defined in parent definition`;
1138
- };
1139
- output?: Array<UNewOutput>;
1140
- config?: {
1141
- schema: TExtensionConfigSchema & {
1142
- [KName in keyof T['config']]?: `Error: Config key '${KName & string}' is already defined in parent schema`;
1143
- };
1144
- };
1145
- factory?(originalFactory: <TFactoryParamsReturn extends AnyParamsInput<NonNullable<T['params']>>>(context?: Expand<{
1146
- config?: T['config'];
1147
- inputs?: ResolvedInputValueOverrides<NonNullable<T['inputs']>>;
1148
- } & ([T['params']] extends [never] ? {} : {
1149
- params?: TFactoryParamsReturn extends ExtensionBlueprintDefineParams ? TFactoryParamsReturn : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(defineParams => defineParams(<params>))`' : Partial<T['params']>;
1150
- })>) => ExtensionDataContainer<NonNullable<T['output']>>, context: {
1151
- node: AppNode;
1152
- apis: ApiHolder;
1153
- config: T['config'] & {
1154
- [key in keyof TExtensionConfigSchema]: z.infer<ReturnType<TExtensionConfigSchema[key]>>;
1155
- };
1156
- inputs: Expand<ResolvedExtensionInputs<T['inputs'] & TExtraInputs>>;
1157
- }): Iterable<UFactoryOutput>;
1158
- } & ([T['params']] extends [never] ? {} : {
1159
- params?: TParamsInput extends ExtensionBlueprintDefineParams ? TParamsInput : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(defineParams => defineParams(<params>))`' : Partial<T['params']>;
1160
- })> & VerifyExtensionFactoryOutput<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UFactoryOutput>): OverridableExtensionDefinition<{
1161
- kind: T['kind'];
1162
- name: T['name'];
1163
- output: ExtensionDataRef extends UNewOutput ? T['output'] : UNewOutput;
1164
- inputs: T['inputs'] & TExtraInputs;
1165
- config: T['config'] & {
1166
- [key in keyof TExtensionConfigSchema]: z.infer<ReturnType<TExtensionConfigSchema[key]>>;
1167
- };
1168
- configInput: T['configInput'] & z.input<z.ZodObject<{
1169
- [key in keyof TExtensionConfigSchema]: ReturnType<TExtensionConfigSchema[key]>;
1170
- }>>;
1171
- }>;
1172
- }
1173
- /**
1174
- * Creates a new extension definition for installation in a Backstage app.
1175
- *
1176
- * @remarks
1177
- *
1178
- * This is a low-level function for creation of extensions with arbitrary inputs
1179
- * and outputs and is typically only intended to be used for advanced overrides
1180
- * or framework-level extensions. For most extension creation needs, it is
1181
- * recommended to use existing {@link ExtensionBlueprint}s instead. You can find
1182
- * blueprints both in the `@backstage/frontend-plugin-api` package as well as
1183
- * other plugin libraries. There is also a list of
1184
- * {@link https://backstage.io/docs/frontend-system/building-plugins/common-extension-blueprints | commonly used blueprints}
1185
- * in the frontend system documentation.
1186
- *
1187
- * Extension definitions that are created with this function can be installed in
1188
- * a Backstage app via a {@link FrontendPlugin} or {@link FrontendModule}.
1189
- *
1190
- * For more details on how extensions work, see the
1191
- * {@link https://backstage.io/docs/frontend-system/architecture/extensions | documentation for extensions}.
1192
- *
1193
- * @example
1194
- *
1195
- * ```ts
1196
- * const myExtension = createExtension({
1197
- * name: 'example',
1198
- * attachTo: { id: 'app', input: 'root' },
1199
- * output: [coreExtensionData.reactElement],
1200
- * factory() {
1201
- * return [coreExtensionData.reactElement(<h1>Hello, world!</h1>)];
1202
- * },
1203
- * });
1204
- * ```
1205
- *
1206
- * @public
1207
- */
1208
- declare function createExtension<UOutput extends ExtensionDataRef, TInputs extends {
1209
- [inputName in string]: ExtensionInput;
1210
- }, TConfigSchema extends {
1211
- [key: string]: (zImpl: typeof z) => z.ZodType;
1212
- }, UFactoryOutput extends ExtensionDataValue<any, any>, const TKind extends string | undefined = undefined, const TName extends string | undefined = undefined, UParentInputs extends ExtensionDataRef = ExtensionDataRef>(options: CreateExtensionOptions<TKind, TName, UOutput, TInputs, TConfigSchema, UFactoryOutput, UParentInputs>): OverridableExtensionDefinition<{
1213
- config: string extends keyof TConfigSchema ? {} : {
1214
- [key in keyof TConfigSchema]: z.infer<ReturnType<TConfigSchema[key]>>;
1215
- };
1216
- configInput: string extends keyof TConfigSchema ? {} : z.input<z.ZodObject<{
1217
- [key in keyof TConfigSchema]: ReturnType<TConfigSchema[key]>;
1218
- }>>;
1219
- output: UOutput extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? ExtensionDataRef<IData, IId, IConfig> : never;
1220
- inputs: TInputs;
1221
- params: never;
1222
- kind: string | undefined extends TKind ? undefined : TKind;
1223
- name: string | undefined extends TName ? undefined : TName;
1224
- }>;
1225
-
1226
- /** @public */
1227
- interface CreateFrontendFeatureLoaderOptions {
1228
- loader(deps: {
1229
- config: ConfigApi;
1230
- }): Iterable<FrontendFeature | FrontendFeatureLoader | Promise<{
1231
- default: FrontendFeature | FrontendFeatureLoader;
1232
- }>> | Promise<Iterable<FrontendFeature | FrontendFeatureLoader | Promise<{
1233
- default: FrontendFeature | FrontendFeatureLoader;
1234
- }>>> | AsyncIterable<FrontendFeature | FrontendFeatureLoader | {
1235
- default: FrontendFeature | FrontendFeatureLoader;
1236
- }>;
1237
- }
1238
- /** @public */
1239
- interface FrontendFeatureLoader {
1240
- readonly $$type: '@backstage/FrontendFeatureLoader';
1241
- }
1242
- /** @public */
1243
- declare function createFrontendFeatureLoader(options: CreateFrontendFeatureLoaderOptions): FrontendFeatureLoader;
1244
-
1245
- /**
1246
- * The specification for this {@link AppNode} in the {@link AppTree}.
1247
- *
1248
- * @public
1249
- * @remarks
1250
- *
1251
- * The specifications for a collection of app nodes is all the information needed
1252
- * to build the tree and instantiate the nodes.
1253
- */
1254
- interface AppNodeSpec {
1255
- readonly id: string;
1256
- readonly attachTo: ExtensionAttachTo;
1257
- readonly extension: Extension<unknown, unknown>;
1258
- readonly disabled: boolean;
1259
- readonly config?: unknown;
1260
- readonly plugin: FrontendPlugin;
1261
- }
1262
- /**
1263
- * The connections from this {@link AppNode} to other nodes.
1264
- *
1265
- * @public
1266
- * @remarks
1267
- *
1268
- * The app node edges are resolved based on the app node specs, regardless of whether
1269
- * adjacent nodes are disabled or not. If no parent attachment is present or
1270
- */
1271
- interface AppNodeEdges {
1272
- readonly attachedTo?: {
1273
- node: AppNode;
1274
- input: string;
1275
- };
1276
- readonly attachments: ReadonlyMap<string, AppNode[]>;
1277
- }
1278
- /**
1279
- * The instance of this {@link AppNode} in the {@link AppTree}.
1280
- *
1281
- * @public
1282
- * @remarks
1283
- *
1284
- * The app node instance is created when the `factory` function of an extension is called.
1285
- * Instances will only be present for nodes in the app that are connected to the root
1286
- * node and not disabled
1287
- */
1288
- interface AppNodeInstance {
1289
- /** Returns a sequence of all extension data refs that were output by this instance */
1290
- getDataRefs(): Iterable<ExtensionDataRef<unknown>>;
1291
- /** Get the output data for a single extension data ref */
1292
- getData<T>(ref: ExtensionDataRef<T>): T | undefined;
1293
- }
1294
- /**
1295
- * A node in the {@link AppTree}.
1296
- *
1297
- * @public
1298
- */
1299
- interface AppNode {
1300
- /** The specification for how this node should be instantiated */
1301
- readonly spec: AppNodeSpec;
1302
- /** The edges from this node to other nodes in the app tree */
1303
- readonly edges: AppNodeEdges;
1304
- /** The instance of this node, if it was instantiated */
1305
- readonly instance?: AppNodeInstance;
1306
- }
1307
- /**
1308
- * The app tree containing all {@link AppNode}s of the app.
1309
- *
1310
- * @public
1311
- */
1312
- interface AppTree {
1313
- /** The root node of the app */
1314
- readonly root: AppNode;
1315
- /** A map of all nodes in the app by ID, including orphaned or disabled nodes */
1316
- readonly nodes: ReadonlyMap<string, AppNode>;
1317
- /** A sequence of all nodes with a parent that is not reachable from the app root node */
1318
- readonly orphans: Iterable<AppNode>;
1319
- }
1320
- /**
1321
- * The API for interacting with the {@link AppTree}.
1322
- *
1323
- * @public
1324
- */
1325
- interface AppTreeApi {
1326
- /**
1327
- * Get the {@link AppTree} for the app.
1328
- */
1329
- getTree(): {
1330
- tree: AppTree;
1331
- };
1332
- /**
1333
- * Get all nodes in the app that are mounted at a given route path.
1334
- */
1335
- getNodesByRoutePath(routePath: string): {
1336
- nodes: AppNode[];
1337
- };
1338
- }
1339
- /**
1340
- * The `ApiRef` of {@link AppTreeApi}.
1341
- *
1342
- * @public
1343
- */
1344
- declare const appTreeApiRef: _backstage_frontend_plugin_api.ApiRef<AppTreeApi>;
1345
-
1346
- /**
1347
- * API reference.
1348
- *
1349
- * @public
1350
- */
1351
- type ApiRef<T> = {
1352
- id: string;
1353
- T: T;
1354
- };
1355
- /**
1356
- * Catch-all {@link ApiRef} type.
1357
- *
1358
- * @public
1359
- */
1360
- type AnyApiRef = ApiRef<unknown>;
1361
- /**
1362
- * Wraps a type with API properties into a type holding their respective {@link ApiRef}s.
1363
- *
1364
- * @public
1365
- */
1366
- type TypesToApiRefs<T> = {
1367
- [key in keyof T]: ApiRef<T[key]>;
1368
- };
1369
- /**
1370
- * Provides lookup of APIs through their {@link ApiRef}s.
1371
- *
1372
- * @public
1373
- */
1374
- type ApiHolder = {
1375
- get<T>(api: ApiRef<T>): T | undefined;
1376
- };
1377
- /**
1378
- * Describes type returning API implementations.
1379
- *
1380
- * @public
1381
- */
1382
- type ApiFactory<Api, Impl extends Api, Deps extends {
1383
- [name in string]: unknown;
1384
- }> = {
1385
- api: ApiRef<Api>;
1386
- deps: TypesToApiRefs<Deps>;
1387
- factory(deps: Deps): Impl;
1388
- };
1389
- /**
1390
- * Catch-all {@link ApiFactory} type.
1391
- *
1392
- * @public
1393
- */
1394
- type AnyApiFactory = ApiFactory<unknown, unknown, {
1395
- [key in string]: unknown;
1396
- }>;
1397
-
1398
- /**
1399
- * React hook for retrieving {@link ApiHolder}, an API catalog.
1400
- *
1401
- * @public
1402
- */
1403
- declare function useApiHolder(): ApiHolder;
1404
- /**
1405
- * React hook for retrieving APIs.
1406
- *
1407
- * @param apiRef - Reference of the API to use.
1408
- * @public
1409
- */
1410
- declare function useApi<T>(apiRef: ApiRef<T>): T;
1411
- /**
1412
- * Wrapper for giving component an API context.
1413
- *
1414
- * @param apis - APIs for the context.
1415
- * @public
1416
- */
1417
- declare function withApis<T extends {}>(apis: TypesToApiRefs<T>): <TProps extends T>(WrappedComponent: ComponentType<TProps>) => {
1418
- (props: PropsWithChildren<Omit<TProps, keyof T>>): react_jsx_runtime.JSX.Element;
1419
- displayName: string;
45
+ /** @public */
46
+ declare const coreExtensionData: {
47
+ title: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<string, "core.title", {}>;
48
+ /** An icon element for the extension. Should be exactly 24x24 pixels. */
49
+ icon: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<IconElement, "core.icon", {}>;
50
+ reactElement: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<JSX$1.Element, "core.reactElement", {}>;
51
+ routePath: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<string, "core.routing.path", {}>;
52
+ routeRef: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<RouteRef<_backstage_frontend_plugin_api.AnyRouteRefParams>, "core.routing.ref", {}>;
1420
53
  };
1421
54
 
1422
55
  /**
1423
- * API reference configuration - holds an ID of the referenced API.
1424
- *
1425
- * @public
1426
- */
1427
- type ApiRefConfig = {
1428
- id: string;
1429
- };
1430
- /**
1431
- * Creates a reference to an API. The provided `id` is a stable identifier for
1432
- * the API implementation.
56
+ * React hook for constructing URLs to routes.
1433
57
  *
1434
58
  * @remarks
1435
59
  *
1436
- * The frontend system infers the owning plugin for an API from the `id`. The
1437
- * recommended pattern is `plugin.<plugin-id>.*` (for example,
1438
- * `plugin.catalog.entity-presentation`). This ensures that other plugins can't
1439
- * mistakenly override your API implementation.
60
+ * See {@link https://backstage.io/docs/plugins/composability#routing-system}
1440
61
  *
1441
- * @param config - The descriptor of the API to reference.
1442
- * @returns An API reference.
62
+ * @param routeRef - The ref to route that should be converted to URL.
63
+ * @returns A function that will in turn return the concrete URL of the `routeRef`, or `undefined` if the route is not available.
1443
64
  * @public
1444
65
  */
1445
- declare function createApiRef<T>(config: ApiRefConfig): ApiRef<T>;
66
+ declare function useRouteRef<TParams extends AnyRouteRefParams>(routeRef: RouteRef<TParams> | SubRouteRef<TParams> | ExternalRouteRef<TParams>): RouteFunc<TParams> | undefined;
1446
67
 
1447
68
  /**
1448
- * Used to infer types for a standalone {@link ApiFactory} that isn't immediately passed
1449
- * to another function.
1450
- *
1451
- * @remarks
1452
- *
1453
- * This function doesn't actually do anything, it's only used to infer types.
1454
- *
1455
- * @public
1456
- */
1457
- declare function createApiFactory<Api, Impl extends Api, Deps extends {
1458
- [name in string]: unknown;
1459
- }>(factory: ApiFactory<Api, Impl, Deps>): ApiFactory<Api, Impl, Deps>;
1460
- /**
1461
- * Used to infer types for a standalone {@link ApiFactory} that isn't immediately passed
1462
- * to another function.
1463
- *
1464
- * @param api - Ref of the API that will be produced by the factory.
1465
- * @param instance - Implementation of the API to use.
69
+ * React hook for retrieving dynamic params from the current URL.
70
+ * @param _routeRef - Ref of the current route.
1466
71
  * @public
1467
72
  */
1468
- declare function createApiFactory<Api, Impl extends Api>(api: ApiRef<Api>, instance: Impl): ApiFactory<Api, Impl, {}>;
73
+ declare function useRouteRefParams<Params extends AnyRouteRefParams>(_routeRef: RouteRef<Params> | SubRouteRef<Params>): Params;
74
+
75
+ /** @public */
76
+ interface CreateFrontendFeatureLoaderOptions {
77
+ loader(deps: {
78
+ config: ConfigApi;
79
+ }): Iterable<FrontendFeature | FrontendFeatureLoader | Promise<{
80
+ default: FrontendFeature | FrontendFeatureLoader;
81
+ }>> | Promise<Iterable<FrontendFeature | FrontendFeatureLoader | Promise<{
82
+ default: FrontendFeature | FrontendFeatureLoader;
83
+ }>>> | AsyncIterable<FrontendFeature | FrontendFeatureLoader | {
84
+ default: FrontendFeature | FrontendFeatureLoader;
85
+ }>;
86
+ }
87
+ /** @public */
88
+ interface FrontendFeatureLoader {
89
+ readonly $$type: '@backstage/FrontendFeatureLoader';
90
+ }
91
+ /** @public */
92
+ declare function createFrontendFeatureLoader(options: CreateFrontendFeatureLoaderOptions): FrontendFeatureLoader;
1469
93
 
1470
94
  /**
1471
95
  * This file contains declarations for common interfaces of auth-related APIs.
@@ -1475,7 +99,10 @@ declare function createApiFactory<Api, Impl extends Api>(api: ApiRef<Api>, insta
1475
99
  * For example, a Google OAuth provider that supports OAuth 2 and OpenID Connect,
1476
100
  * would be declared as follows:
1477
101
  *
1478
- * const googleAuthApiRef = createApiRef<OAuthApi & OpenIDConnectApi>({ ... })
102
+ * const googleAuthApiRef = createApiRef<OAuthApi & OpenIDConnectApi>().with({
103
+ * id: 'core.auth.google',
104
+ * pluginId: 'app',
105
+ * })
1479
106
  */
1480
107
  /**
1481
108
  * Information about the auth provider.
@@ -1498,8 +125,13 @@ type AuthProviderInfo = {
1498
125
  title: string;
1499
126
  /**
1500
127
  * Icon for the auth provider.
128
+ *
129
+ * @remarks
130
+ *
131
+ * Accepts either an `IconElement` (e.g. `<MyIcon />`) or an `IconComponent`
132
+ * (e.g. `MyIcon`). Prefer passing `IconElement`.
1501
133
  */
1502
- icon: IconComponent;
134
+ icon: IconComponent | IconElement;
1503
135
  /**
1504
136
  * Optional user friendly messaage to display for the auth provider.
1505
137
  */
@@ -1743,7 +375,9 @@ type SessionApi = {
1743
375
  * Note that the ID token payload is only guaranteed to contain the user's numerical Google ID,
1744
376
  * email and expiration information. Do not rely on any other fields, as they might not be present.
1745
377
  */
1746
- declare const googleAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
378
+ declare const googleAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.google"> & {
379
+ readonly $$type: "@backstage/ApiRef";
380
+ };
1747
381
  /**
1748
382
  * Provides authentication towards GitHub APIs.
1749
383
  *
@@ -1753,7 +387,9 @@ declare const googleAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfo
1753
387
  * See {@link https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/}
1754
388
  * for a full list of supported scopes.
1755
389
  */
1756
- declare const githubAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
390
+ declare const githubAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.github"> & {
391
+ readonly $$type: "@backstage/ApiRef";
392
+ };
1757
393
  /**
1758
394
  * Provides authentication towards Okta APIs.
1759
395
  *
@@ -1763,7 +399,9 @@ declare const githubAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIden
1763
399
  * See {@link https://developer.okta.com/docs/guides/implement-oauth-for-okta/scopes/}
1764
400
  * for a full list of supported scopes.
1765
401
  */
1766
- declare const oktaAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
402
+ declare const oktaAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.okta"> & {
403
+ readonly $$type: "@backstage/ApiRef";
404
+ };
1767
405
  /**
1768
406
  * Provides authentication towards GitLab APIs.
1769
407
  *
@@ -1773,7 +411,9 @@ declare const oktaAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoAp
1773
411
  * See {@link https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#limiting-scopes-of-a-personal-access-token}
1774
412
  * for a full list of supported scopes.
1775
413
  */
1776
- declare const gitlabAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
414
+ declare const gitlabAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.gitlab"> & {
415
+ readonly $$type: "@backstage/ApiRef";
416
+ };
1777
417
  /**
1778
418
  * Provides authentication towards Microsoft APIs and identities.
1779
419
  *
@@ -1784,13 +424,17 @@ declare const gitlabAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfo
1784
424
  * - {@link https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent}
1785
425
  * - {@link https://docs.microsoft.com/en-us/graph/permissions-reference}
1786
426
  */
1787
- declare const microsoftAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
427
+ declare const microsoftAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.microsoft"> & {
428
+ readonly $$type: "@backstage/ApiRef";
429
+ };
1788
430
  /**
1789
431
  * Provides authentication towards OneLogin APIs.
1790
432
  *
1791
433
  * @public
1792
434
  */
1793
- declare const oneloginAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
435
+ declare const oneloginAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.onelogin"> & {
436
+ readonly $$type: "@backstage/ApiRef";
437
+ };
1794
438
  /**
1795
439
  * Provides authentication towards Bitbucket APIs.
1796
440
  *
@@ -1800,7 +444,9 @@ declare const oneloginAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileIn
1800
444
  * See {@link https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/}
1801
445
  * for a full list of supported scopes.
1802
446
  */
1803
- declare const bitbucketAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
447
+ declare const bitbucketAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.bitbucket"> & {
448
+ readonly $$type: "@backstage/ApiRef";
449
+ };
1804
450
  /**
1805
451
  * Provides authentication towards Bitbucket Server APIs.
1806
452
  *
@@ -1810,7 +456,9 @@ declare const bitbucketAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageI
1810
456
  * See {@link https://confluence.atlassian.com/bitbucketserver/bitbucket-oauth-2-0-provider-api-1108483661.html#BitbucketOAuth2.0providerAPI-scopes}
1811
457
  * for a full list of supported scopes.
1812
458
  */
1813
- declare const bitbucketServerAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
459
+ declare const bitbucketServerAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.bitbucket-server"> & {
460
+ readonly $$type: "@backstage/ApiRef";
461
+ };
1814
462
  /**
1815
463
  * Provides authentication towards Atlassian APIs.
1816
464
  *
@@ -1820,7 +468,9 @@ declare const bitbucketServerAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & Back
1820
468
  * See {@link https://developer.atlassian.com/cloud/jira/platform/scopes-for-connect-and-oauth-2-3LO-apps/}
1821
469
  * for a full list of supported scopes.
1822
470
  */
1823
- declare const atlassianAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
471
+ declare const atlassianAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.atlassian"> & {
472
+ readonly $$type: "@backstage/ApiRef";
473
+ };
1824
474
  /**
1825
475
  * Provides authentication towards VMware Cloud APIs and identities.
1826
476
  *
@@ -1830,7 +480,9 @@ declare const atlassianAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageI
1830
480
  * For more info about VMware Cloud identity and access management:
1831
481
  * - {@link https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-53D39337-D93A-4B84-BD18-DDF43C21479A.html}
1832
482
  */
1833
- declare const vmwareCloudAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
483
+ declare const vmwareCloudAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.vmware-cloud"> & {
484
+ readonly $$type: "@backstage/ApiRef";
485
+ };
1834
486
  /**
1835
487
  * Provides authentication towards OpenShift APIs and identities.
1836
488
  *
@@ -1842,12 +494,22 @@ declare const vmwareCloudAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & Profil
1842
494
  * {@link https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html-single/authentication_and_authorization/index#tokens-scoping-about_configuring-internal-oauth}
1843
495
  * for available scopes.
1844
496
  */
1845
- declare const openshiftAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
497
+ declare const openshiftAuthApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi, "core.auth.openshift"> & {
498
+ readonly $$type: "@backstage/ApiRef";
499
+ };
1846
500
 
1847
501
  /**
1848
502
  * Message handled by the {@link AlertApi}.
1849
503
  *
1850
504
  * @public
505
+ * @deprecated Use {@link ToastApiMessage} from {@link ToastApi} instead. AlertApi will be removed in a future release.
506
+ *
507
+ * Migration guide:
508
+ * - `message` becomes `title`
509
+ * - `severity: 'error'` becomes `status: 'danger'`
510
+ * - `severity: 'success' | 'info' | 'warning'` becomes `status: 'success' | 'info' | 'warning'`
511
+ * - `display: 'transient'` becomes `timeout: 5000` (or custom milliseconds)
512
+ * - `display: 'permanent'` means omitting `timeout`
1851
513
  */
1852
514
  type AlertMessage = {
1853
515
  message: string;
@@ -1858,6 +520,23 @@ type AlertMessage = {
1858
520
  * The alert API is used to report alerts to the app, and display them to the user.
1859
521
  *
1860
522
  * @public
523
+ * @deprecated Use {@link ToastApi} instead. AlertApi will be removed in a future release.
524
+ *
525
+ * ToastApi provides richer notification features including:
526
+ * - Title and optional description
527
+ * - Action links
528
+ * - Custom icons
529
+ * - Per-toast timeout control
530
+ * - Programmatic dismiss via returned key
531
+ *
532
+ * @example
533
+ * ```typescript
534
+ * // Before (AlertApi)
535
+ * alertApi.post({ message: 'Saved!', severity: 'success', display: 'transient' });
536
+ *
537
+ * // After (ToastApi)
538
+ * toastApi.post({ title: 'Saved!', status: 'success', timeout: 5000 });
539
+ * ```
1861
540
  */
1862
541
  type AlertApi = {
1863
542
  /**
@@ -1873,8 +552,11 @@ type AlertApi = {
1873
552
  * The {@link ApiRef} of {@link AlertApi}.
1874
553
  *
1875
554
  * @public
555
+ * @deprecated Use {@link toastApiRef} instead. AlertApi will be removed in a future release.
1876
556
  */
1877
- declare const alertApiRef: ApiRef<AlertApi>;
557
+ declare const alertApiRef: _backstage_frontend_plugin_api.ApiRef<AlertApi, "core.alert"> & {
558
+ readonly $$type: "@backstage/ApiRef";
559
+ };
1878
560
 
1879
561
  /** @public */
1880
562
  type AppLanguageApi = {
@@ -1892,7 +574,9 @@ type AppLanguageApi = {
1892
574
  /**
1893
575
  * @public
1894
576
  */
1895
- declare const appLanguageApiRef: ApiRef<AppLanguageApi>;
577
+ declare const appLanguageApiRef: _backstage_frontend_plugin_api.ApiRef<AppLanguageApi, "core.applanguage"> & {
578
+ readonly $$type: "@backstage/ApiRef";
579
+ };
1896
580
 
1897
581
  /**
1898
582
  * Describes a theme provided by the app.
@@ -1951,7 +635,9 @@ type AppThemeApi = {
1951
635
  *
1952
636
  * @public
1953
637
  */
1954
- declare const appThemeApiRef: ApiRef<AppThemeApi>;
638
+ declare const appThemeApiRef: _backstage_frontend_plugin_api.ApiRef<AppThemeApi, "core.apptheme"> & {
639
+ readonly $$type: "@backstage/ApiRef";
640
+ };
1955
641
 
1956
642
  /** @public */
1957
643
  interface ExtensionBoundaryProps {
@@ -2048,12 +734,17 @@ declare const ErrorDisplay: {
2048
734
  * Tab configuration for page navigation
2049
735
  * @public
2050
736
  */
2051
- interface PageTab {
737
+ interface PageLayoutTab {
2052
738
  id: string;
2053
739
  label: string;
2054
740
  icon?: IconElement;
2055
741
  href: string;
2056
742
  }
743
+ /**
744
+ * @deprecated Use {@link PageLayoutTab} instead
745
+ * @public
746
+ */
747
+ type PageTab = PageLayoutTab;
2057
748
  /**
2058
749
  * Props for the PageLayout component
2059
750
  * @public
@@ -2063,7 +754,7 @@ interface PageLayoutProps {
2063
754
  icon?: IconElement;
2064
755
  noHeader?: boolean;
2065
756
  headerActions?: Array<JSX.Element | null>;
2066
- tabs?: PageTab[];
757
+ tabs?: PageLayoutTab[];
2067
758
  children?: ReactNode;
2068
759
  }
2069
760
  /**
@@ -2091,7 +782,9 @@ interface SwappableComponentsApi {
2091
782
  *
2092
783
  * @public
2093
784
  */
2094
- declare const swappableComponentsApiRef: _backstage_frontend_plugin_api.ApiRef<SwappableComponentsApi>;
785
+ declare const swappableComponentsApiRef: _backstage_frontend_plugin_api.ApiRef<SwappableComponentsApi, "core.swappable-components"> & {
786
+ readonly $$type: "@backstage/ApiRef";
787
+ };
2095
788
 
2096
789
  /**
2097
790
  * The Config API is used to provide a mechanism to access the
@@ -2105,7 +798,9 @@ type ConfigApi = Config;
2105
798
  *
2106
799
  * @public
2107
800
  */
2108
- declare const configApiRef: ApiRef<ConfigApi>;
801
+ declare const configApiRef: _backstage_frontend_plugin_api.ApiRef<Config, "core.config"> & {
802
+ readonly $$type: "@backstage/ApiRef";
803
+ };
2109
804
 
2110
805
  /**
2111
806
  * The discovery API is used to provide a mechanism for plugins to
@@ -2141,7 +836,9 @@ type DiscoveryApi = {
2141
836
  *
2142
837
  * @public
2143
838
  */
2144
- declare const discoveryApiRef: ApiRef<DiscoveryApi>;
839
+ declare const discoveryApiRef: _backstage_frontend_plugin_api.ApiRef<DiscoveryApi, "core.discovery"> & {
840
+ readonly $$type: "@backstage/ApiRef";
841
+ };
2145
842
 
2146
843
  /**
2147
844
  * Mirrors the JavaScript Error class, for the purpose of
@@ -2208,7 +905,9 @@ type ErrorApi = {
2208
905
  *
2209
906
  * @public
2210
907
  */
2211
- declare const errorApiRef: ApiRef<ErrorApi>;
908
+ declare const errorApiRef: _backstage_frontend_plugin_api.ApiRef<ErrorApi, "core.error"> & {
909
+ readonly $$type: "@backstage/ApiRef";
910
+ };
2212
911
 
2213
912
  /**
2214
913
  * Feature flag descriptor.
@@ -2302,7 +1001,9 @@ interface FeatureFlagsApi {
2302
1001
  *
2303
1002
  * @public
2304
1003
  */
2305
- declare const featureFlagsApiRef: ApiRef<FeatureFlagsApi>;
1004
+ declare const featureFlagsApiRef: _backstage_frontend_plugin_api.ApiRef<FeatureFlagsApi, "core.featureflags"> & {
1005
+ readonly $$type: "@backstage/ApiRef";
1006
+ };
2306
1007
 
2307
1008
  /**
2308
1009
  * A wrapper for the fetch API, that has additional behaviors such as the
@@ -2333,7 +1034,9 @@ type FetchApi = {
2333
1034
  *
2334
1035
  * @public
2335
1036
  */
2336
- declare const fetchApiRef: ApiRef<FetchApi>;
1037
+ declare const fetchApiRef: _backstage_frontend_plugin_api.ApiRef<FetchApi, "core.fetch"> & {
1038
+ readonly $$type: "@backstage/ApiRef";
1039
+ };
2337
1040
 
2338
1041
  /**
2339
1042
  * API for accessing app icons.
@@ -2356,7 +1059,9 @@ interface IconsApi {
2356
1059
  *
2357
1060
  * @public
2358
1061
  */
2359
- declare const iconsApiRef: _backstage_frontend_plugin_api.ApiRef<IconsApi>;
1062
+ declare const iconsApiRef: _backstage_frontend_plugin_api.ApiRef<IconsApi, "core.icons"> & {
1063
+ readonly $$type: "@backstage/ApiRef";
1064
+ };
2360
1065
 
2361
1066
  /**
2362
1067
  * The Identity API used to identify and get information about the signed in user.
@@ -2391,7 +1096,9 @@ type IdentityApi = {
2391
1096
  *
2392
1097
  * @public
2393
1098
  */
2394
- declare const identityApiRef: ApiRef<IdentityApi>;
1099
+ declare const identityApiRef: _backstage_frontend_plugin_api.ApiRef<IdentityApi, "core.identity"> & {
1100
+ readonly $$type: "@backstage/ApiRef";
1101
+ };
2395
1102
 
2396
1103
  /**
2397
1104
  * A handle for an open dialog that can be used to interact with it.
@@ -2414,7 +1121,7 @@ interface DialogApiDialog<TResult = void> {
2414
1121
  /**
2415
1122
  * Replaces the content of the dialog with the provided element or component, causing it to be rerenedered.
2416
1123
  */
2417
- update(elementOrComponent: React.JSX.Element | ((props: {
1124
+ update(elementOrComponent: JSX.Element | ((props: {
2418
1125
  dialog: DialogApiDialog<TResult>;
2419
1126
  }) => JSX.Element)): void;
2420
1127
  /**
@@ -2535,7 +1242,9 @@ interface DialogApi {
2535
1242
  *
2536
1243
  * @public
2537
1244
  */
2538
- declare const dialogApiRef: _backstage_frontend_plugin_api.ApiRef<DialogApi>;
1245
+ declare const dialogApiRef: _backstage_frontend_plugin_api.ApiRef<DialogApi, "core.dialog"> & {
1246
+ readonly $$type: "@backstage/ApiRef";
1247
+ };
2539
1248
 
2540
1249
  /**
2541
1250
  * Describes how to handle auth requests. Both how to show them to the user, and what to do when
@@ -2633,7 +1342,9 @@ type OAuthRequestApi = {
2633
1342
  *
2634
1343
  * @public
2635
1344
  */
2636
- declare const oauthRequestApiRef: ApiRef<OAuthRequestApi>;
1345
+ declare const oauthRequestApiRef: _backstage_frontend_plugin_api.ApiRef<OAuthRequestApi, "core.oauthrequest"> & {
1346
+ readonly $$type: "@backstage/ApiRef";
1347
+ };
2637
1348
 
2638
1349
  /**
2639
1350
  * TS magic for handling route parameters.
@@ -2666,7 +1377,9 @@ interface RouteResolutionApi {
2666
1377
  *
2667
1378
  * @public
2668
1379
  */
2669
- declare const routeResolutionApiRef: _backstage_frontend_plugin_api.ApiRef<RouteResolutionApi>;
1380
+ declare const routeResolutionApiRef: _backstage_frontend_plugin_api.ApiRef<RouteResolutionApi, "core.route-resolution"> & {
1381
+ readonly $$type: "@backstage/ApiRef";
1382
+ };
2670
1383
 
2671
1384
  /**
2672
1385
  * A snapshot in time of the current known value of a storage key.
@@ -2746,7 +1459,9 @@ interface StorageApi {
2746
1459
  *
2747
1460
  * @public
2748
1461
  */
2749
- declare const storageApiRef: ApiRef<StorageApi>;
1462
+ declare const storageApiRef: _backstage_frontend_plugin_api.ApiRef<StorageApi, "core.storage"> & {
1463
+ readonly $$type: "@backstage/ApiRef";
1464
+ };
2750
1465
 
2751
1466
  /**
2752
1467
  * Represents an event worth tracking in an analytics system that could inform
@@ -2869,7 +1584,207 @@ type AnalyticsApi = {
2869
1584
  *
2870
1585
  * @public
2871
1586
  */
2872
- declare const analyticsApiRef: ApiRef<AnalyticsApi>;
1587
+ declare const analyticsApiRef: _backstage_frontend_plugin_api.ApiRef<AnalyticsApi, "core.analytics"> & {
1588
+ readonly $$type: "@backstage/ApiRef";
1589
+ };
1590
+
1591
+ /**
1592
+ * React hook for retrieving {@link ApiHolder}, an API catalog.
1593
+ *
1594
+ * @public
1595
+ */
1596
+ declare function useApiHolder(): ApiHolder;
1597
+ /**
1598
+ * React hook for retrieving APIs.
1599
+ *
1600
+ * @param apiRef - Reference of the API to use.
1601
+ * @public
1602
+ */
1603
+ declare function useApi<T>(apiRef: ApiRef<T>): T;
1604
+ /**
1605
+ * Wrapper for giving component an API context.
1606
+ *
1607
+ * @param apis - APIs for the context.
1608
+ * @deprecated Use `withApis` from `@backstage/core-compat-api` instead.
1609
+ * @public
1610
+ */
1611
+ declare function withApis<T extends {}>(apis: TypesToApiRefs<T>): <TProps extends T>(WrappedComponent: ComponentType<TProps>) => {
1612
+ (props: PropsWithChildren<Omit<TProps, keyof T>>): react_jsx_runtime.JSX.Element;
1613
+ displayName: string;
1614
+ };
1615
+
1616
+ /**
1617
+ * API reference configuration - holds an ID of the referenced API.
1618
+ *
1619
+ * @public
1620
+ */
1621
+ type ApiRefConfig = {
1622
+ id: string;
1623
+ };
1624
+ /**
1625
+ * Creates a reference to an API.
1626
+ *
1627
+ * @remarks
1628
+ *
1629
+ * The `id` is a stable identifier for the API implementation. The frontend
1630
+ * system infers the owning plugin for an API from the `id`. When using the
1631
+ * builder form, you can instead provide a `pluginId` explicitly. The
1632
+ * recommended pattern is `plugin.<plugin-id>.*` (for example,
1633
+ * `plugin.catalog.entity-presentation`). This ensures that other plugins can't
1634
+ * mistakenly override your API implementation.
1635
+ *
1636
+ * The recommended way to create an API reference is:
1637
+ *
1638
+ * ```ts
1639
+ * const myApiRef = createApiRef<MyApi>().with({
1640
+ * id: 'my-api',
1641
+ * pluginId: 'my-plugin',
1642
+ * });
1643
+ * ```
1644
+ *
1645
+ * The legacy way to create an API reference is:
1646
+ *
1647
+ * ```ts
1648
+ * const myApiRef = createApiRef<MyApi>({ id: 'plugin.my.api' });
1649
+ * ```
1650
+ *
1651
+ * @public
1652
+ */
1653
+ /**
1654
+ * Creates a reference to an API.
1655
+ *
1656
+ * @deprecated Use `createApiRef<T>().with(...)` instead.
1657
+ * @public
1658
+ */
1659
+ declare function createApiRef<T>(config: ApiRefConfig): ApiRef<T> & {
1660
+ readonly $$type: '@backstage/ApiRef';
1661
+ };
1662
+ /**
1663
+ * Creates a reference to an API.
1664
+ *
1665
+ * @remarks
1666
+ *
1667
+ * Returns a builder with a `.with()` method for providing the API reference
1668
+ * configuration.
1669
+ *
1670
+ * @public
1671
+ */
1672
+ declare function createApiRef<T>(): {
1673
+ with<const TId extends string>(config: ApiRefConfig & {
1674
+ id: TId;
1675
+ pluginId?: string;
1676
+ }): ApiRef<T, TId> & {
1677
+ readonly $$type: '@backstage/ApiRef';
1678
+ };
1679
+ };
1680
+
1681
+ /**
1682
+ * Used to infer types for a standalone {@link ApiFactory} that isn't immediately passed
1683
+ * to another function.
1684
+ *
1685
+ * @remarks
1686
+ *
1687
+ * This function doesn't actually do anything, it's only used to infer types.
1688
+ *
1689
+ * @public
1690
+ */
1691
+ declare function createApiFactory<Api, Impl extends Api, Deps extends {
1692
+ [name in string]: unknown;
1693
+ }>(factory: ApiFactory<Api, Impl, Deps>): ApiFactory<Api, Impl, Deps>;
1694
+ /**
1695
+ * Used to infer types for a standalone {@link ApiFactory} that isn't immediately passed
1696
+ * to another function.
1697
+ *
1698
+ * @param api - Ref of the API that will be produced by the factory.
1699
+ * @param instance - Implementation of the API to use.
1700
+ * @public
1701
+ */
1702
+ declare function createApiFactory<Api, Impl extends Api>(api: ApiRef<Api>, instance: Impl): ApiFactory<Api, Impl, {}>;
1703
+
1704
+ /**
1705
+ * Link item for toast notifications.
1706
+ *
1707
+ * @public
1708
+ */
1709
+ type ToastApiMessageLink = {
1710
+ /** Display text for the link */
1711
+ label: string;
1712
+ /** URL the link points to */
1713
+ href: string;
1714
+ };
1715
+ /**
1716
+ * Message handled by the {@link ToastApi}.
1717
+ *
1718
+ * @public
1719
+ */
1720
+ type ToastApiMessage = {
1721
+ /** Title of the toast (required) */
1722
+ title: ReactNode;
1723
+ /** Optional description text */
1724
+ description?: ReactNode;
1725
+ /** Status variant of the toast - defaults to 'success' */
1726
+ status?: 'neutral' | 'info' | 'success' | 'warning' | 'danger';
1727
+ /** Optional array of links to display */
1728
+ links?: ToastApiMessageLink[];
1729
+ /** Timeout in milliseconds before auto-dismiss. If not set, toast is permanent. */
1730
+ timeout?: number;
1731
+ };
1732
+ /**
1733
+ * Handle returned by {@link ToastApi.post} that allows programmatic control
1734
+ * of the posted toast.
1735
+ *
1736
+ * @public
1737
+ */
1738
+ type ToastApiPostResult = {
1739
+ /** Dismiss the toast. */
1740
+ close(): void;
1741
+ };
1742
+ /**
1743
+ * The toast API is used to display toast notifications to the user.
1744
+ *
1745
+ * @remarks
1746
+ * This API provides richer notification capabilities than the AlertApi,
1747
+ * including title/description, links, and per-toast timeout control.
1748
+ *
1749
+ * @example
1750
+ * ```tsx
1751
+ * const toastApi = useApi(toastApiRef);
1752
+ *
1753
+ * // Full-featured toast
1754
+ * toastApi.post({
1755
+ * title: 'Entity saved',
1756
+ * description: 'Your changes have been saved successfully.',
1757
+ * status: 'success',
1758
+ * timeout: 5000,
1759
+ * links: [{ label: 'View entity', href: '/catalog/default/component/my-service' }],
1760
+ * });
1761
+ *
1762
+ * // Simple toast
1763
+ * toastApi.post({ title: 'Processing...', status: 'info' });
1764
+ *
1765
+ * // Programmatic dismiss
1766
+ * const { close } = toastApi.post({ title: 'Uploading...', status: 'info' });
1767
+ * // Later...
1768
+ * close();
1769
+ * ```
1770
+ *
1771
+ * @public
1772
+ */
1773
+ type ToastApi = {
1774
+ /**
1775
+ * Post a toast notification for display to the user.
1776
+ *
1777
+ * @param toast - The toast message to display
1778
+ * @returns A handle with a `close()` method to programmatically dismiss the toast
1779
+ */
1780
+ post(toast: ToastApiMessage): ToastApiPostResult;
1781
+ };
1782
+ /**
1783
+ * The {@link ApiRef} of {@link ToastApi}.
1784
+ *
1785
+ * @public
1786
+ */
1787
+ declare const toastApiRef: ApiRef<ToastApi>;
2873
1788
 
2874
1789
  /** @public */
2875
1790
  interface TranslationRef<TId extends string = string, TMessages extends {
@@ -3248,7 +2163,9 @@ type TranslationApi = {
3248
2163
  /**
3249
2164
  * @public
3250
2165
  */
3251
- declare const translationApiRef: ApiRef<TranslationApi>;
2166
+ declare const translationApiRef: _backstage_frontend_plugin_api.ApiRef<TranslationApi, "core.translation"> & {
2167
+ readonly $$type: "@backstage/ApiRef";
2168
+ };
3252
2169
 
3253
2170
  /**
3254
2171
  * API for retrieving plugin-scoped header actions.
@@ -3272,7 +2189,9 @@ type PluginHeaderActionsApi = {
3272
2189
  *
3273
2190
  * @public
3274
2191
  */
3275
- declare const pluginHeaderActionsApiRef: _backstage_frontend_plugin_api.ApiRef<PluginHeaderActionsApi>;
2192
+ declare const pluginHeaderActionsApiRef: _backstage_frontend_plugin_api.ApiRef<PluginHeaderActionsApi, "core.plugin-header-actions"> & {
2193
+ readonly $$type: "@backstage/ApiRef";
2194
+ };
3276
2195
 
3277
2196
  /**
3278
2197
  * Gets a pre-configured analytics tracker.
@@ -3281,7 +2200,10 @@ declare const pluginHeaderActionsApiRef: _backstage_frontend_plugin_api.ApiRef<P
3281
2200
  */
3282
2201
  declare function useAnalytics(): AnalyticsTracker;
3283
2202
 
3284
- /** @public */
2203
+ /**
2204
+ * @public
2205
+ * @deprecated Use `AnalyticsImplementationFactory` from `@backstage/plugin-app-react` instead.
2206
+ */
3285
2207
  type AnalyticsImplementationFactory<Deps extends {
3286
2208
  [name in string]: unknown;
3287
2209
  } = {}> = {
@@ -3292,6 +2214,7 @@ type AnalyticsImplementationFactory<Deps extends {
3292
2214
  * Creates analytics implementations.
3293
2215
  *
3294
2216
  * @public
2217
+ * @deprecated Use `AnalyticsImplementationBlueprint` from `@backstage/plugin-app-react` instead.
3295
2218
  */
3296
2219
  declare const AnalyticsImplementationBlueprint: _backstage_frontend_plugin_api.ExtensionBlueprint<{
3297
2220
  kind: "analytics";
@@ -3344,6 +2267,10 @@ declare const AppRootElementBlueprint: _backstage_frontend_plugin_api.ExtensionB
3344
2267
  * Creates extensions that make up the items of the nav bar.
3345
2268
  *
3346
2269
  * @public
2270
+ * @deprecated Nav items are now automatically inferred from `PageBlueprint`
2271
+ * extensions based on their `title` and `icon` params. You can remove your
2272
+ * `NavItemBlueprint` usage and instead pass `title` and `icon` directly to
2273
+ * the `PageBlueprint`.
3347
2274
  */
3348
2275
  declare const NavItemBlueprint: _backstage_frontend_plugin_api.ExtensionBlueprint<{
3349
2276
  kind: "nav-item";
@@ -3377,10 +2304,6 @@ declare const NavItemBlueprint: _backstage_frontend_plugin_api.ExtensionBlueprin
3377
2304
  declare const PageBlueprint: _backstage_frontend_plugin_api.ExtensionBlueprint<{
3378
2305
  kind: "page";
3379
2306
  params: {
3380
- /**
3381
- * @deprecated Use the `path` param instead.
3382
- */
3383
- defaultPath?: [Error: `Use the 'path' param instead`];
3384
2307
  path: string;
3385
2308
  title?: string;
3386
2309
  icon?: IconElement;
@@ -3511,5 +2434,5 @@ declare const PluginHeaderActionBlueprint: _backstage_frontend_plugin_api.Extens
3511
2434
  dataRefs: never;
3512
2435
  }>;
3513
2436
 
3514
- export { AnalyticsContext, AnalyticsImplementationBlueprint, ApiBlueprint, AppRootElementBlueprint, ErrorDisplay, ExtensionBoundary, FeatureFlagState, NavItemBlueprint, NotFoundErrorPage, PageBlueprint, PageLayout, PluginHeaderActionBlueprint, Progress, SessionState, SubPageBlueprint, alertApiRef, analyticsApiRef, appLanguageApiRef, appThemeApiRef, appTreeApiRef, atlassianAuthApiRef, bitbucketAuthApiRef, bitbucketServerAuthApiRef, configApiRef, coreExtensionData, createApiFactory, createApiRef, createExtension, createExtensionBlueprint, createExtensionBlueprintParams, createExtensionDataRef, createExtensionInput, createExternalRouteRef, createFrontendFeatureLoader, createFrontendModule, createFrontendPlugin, createRouteRef, createSubRouteRef, createSwappableComponent, createTranslationMessages, createTranslationRef, createTranslationResource, dialogApiRef, discoveryApiRef, errorApiRef, featureFlagsApiRef, fetchApiRef, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, iconsApiRef, identityApiRef, microsoftAuthApiRef, oauthRequestApiRef, oktaAuthApiRef, oneloginAuthApiRef, openshiftAuthApiRef, pluginHeaderActionsApiRef, routeResolutionApiRef, storageApiRef, swappableComponentsApiRef, translationApiRef, useAnalytics, useApi, useApiHolder, useAppNode, useRouteRef, useRouteRefParams, useTranslationRef, vmwareCloudAuthApiRef, withApis };
3515
- export type { AlertApi, AlertMessage, AnalyticsApi, AnalyticsContextValue, AnalyticsEvent, AnalyticsEventAttributes, AnalyticsImplementation, AnalyticsImplementationFactory, AnalyticsTracker, AnyApiFactory, AnyApiRef, AnyExtensionDataRef, AnyRouteRefParams, ApiFactory, ApiHolder, ApiRef, ApiRefConfig, AppLanguageApi, AppNode, AppNodeEdges, AppNodeInstance, AppNodeSpec, AppTheme, AppThemeApi, AppTree, AppTreeApi, AuthProviderInfo, AuthRequestOptions, BackstageIdentityApi, BackstageIdentityResponse, BackstageUserIdentity, ConfigApi, ConfigurableExtensionDataRef, CreateExtensionBlueprintOptions, CreateExtensionOptions, CreateFrontendFeatureLoaderOptions, CreateFrontendModuleOptions, CreateSwappableComponentOptions, DialogApi, DialogApiDialog, DiscoveryApi, ErrorApi, ErrorApiError, ErrorApiErrorContext, ErrorDisplayProps, Extension, ExtensionAttachTo, ExtensionAttachToSpec, ExtensionBlueprint, ExtensionBlueprintDefineParams, ExtensionBlueprintParameters, ExtensionBlueprintParams, ExtensionBoundaryProps, ExtensionDataContainer, ExtensionDataRef, ExtensionDataRefToValue, ExtensionDataValue, ExtensionDefinition, ExtensionDefinitionAttachTo, ExtensionDefinitionParameters, ExtensionFactoryMiddleware, ExtensionInput, ExternalRouteRef, FeatureFlag, FeatureFlagConfig, FeatureFlagsApi, FeatureFlagsSaveOptions, FetchApi, FrontendFeature, FrontendFeatureLoader, FrontendModule, FrontendPlugin, FrontendPluginInfo, FrontendPluginInfoOptions, IconComponent, IconElement, IconsApi, IdentityApi, NotFoundErrorPageProps, OAuthApi, OAuthRequestApi, OAuthRequester, OAuthRequesterOptions, OAuthScope, OpenIdConnectApi, OverridableExtensionDefinition, OverridableFrontendPlugin, PageLayoutProps, PageTab, PendingOAuthRequest, PluginHeaderActionsApi, PluginOptions, PortableSchema, ProfileInfo, ProfileInfoApi, ProgressProps, ResolvedExtensionInput, ResolvedExtensionInputs, RouteFunc, RouteRef, RouteResolutionApi, SessionApi, StorageApi, StorageValueSnapshot, SubRouteRef, SwappableComponentRef, SwappableComponentsApi, TranslationApi, TranslationFunction, TranslationMessages, TranslationMessagesOptions, TranslationRef, TranslationRefOptions, TranslationResource, TranslationResourceOptions, TranslationSnapshot, TypesToApiRefs };
2437
+ export { AnalyticsContext, AnalyticsImplementationBlueprint, AnyApiFactory, AnyRouteRefParams, ApiBlueprint, ApiFactory, ApiHolder, ApiRef, AppNode, AppRootElementBlueprint, ErrorDisplay, ExtensionBoundary, ExternalRouteRef, FeatureFlagState, FrontendFeature, FrontendPlugin, IconComponent, IconElement, NavItemBlueprint, NotFoundErrorPage, PageBlueprint, PageLayout, PluginHeaderActionBlueprint, Progress, RouteRef, SessionState, SubPageBlueprint, SubRouteRef, TypesToApiRefs, alertApiRef, analyticsApiRef, appLanguageApiRef, appThemeApiRef, atlassianAuthApiRef, bitbucketAuthApiRef, bitbucketServerAuthApiRef, configApiRef, coreExtensionData, createApiFactory, createApiRef, createFrontendFeatureLoader, createSwappableComponent, createTranslationMessages, createTranslationRef, createTranslationResource, dialogApiRef, discoveryApiRef, errorApiRef, featureFlagsApiRef, fetchApiRef, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, iconsApiRef, identityApiRef, microsoftAuthApiRef, oauthRequestApiRef, oktaAuthApiRef, oneloginAuthApiRef, openshiftAuthApiRef, pluginHeaderActionsApiRef, routeResolutionApiRef, storageApiRef, swappableComponentsApiRef, toastApiRef, translationApiRef, useAnalytics, useApi, useApiHolder, useAppNode, useRouteRef, useRouteRefParams, useTranslationRef, vmwareCloudAuthApiRef, withApis };
2438
+ export type { AlertApi, AlertMessage, AnalyticsApi, AnalyticsContextValue, AnalyticsEvent, AnalyticsEventAttributes, AnalyticsImplementation, AnalyticsImplementationFactory, AnalyticsTracker, ApiRefConfig, AppLanguageApi, AppTheme, AppThemeApi, AuthProviderInfo, AuthRequestOptions, BackstageIdentityApi, BackstageIdentityResponse, BackstageUserIdentity, ConfigApi, CreateFrontendFeatureLoaderOptions, CreateSwappableComponentOptions, DialogApi, DialogApiDialog, DiscoveryApi, ErrorApi, ErrorApiError, ErrorApiErrorContext, ErrorDisplayProps, ExtensionBoundaryProps, FeatureFlag, FeatureFlagsApi, FeatureFlagsSaveOptions, FetchApi, FrontendFeatureLoader, IconsApi, IdentityApi, NotFoundErrorPageProps, OAuthApi, OAuthRequestApi, OAuthRequester, OAuthRequesterOptions, OAuthScope, OpenIdConnectApi, PageLayoutProps, PageLayoutTab, PageTab, PendingOAuthRequest, PluginHeaderActionsApi, ProfileInfo, ProfileInfoApi, ProgressProps, RouteFunc, RouteResolutionApi, SessionApi, StorageApi, StorageValueSnapshot, SwappableComponentRef, SwappableComponentsApi, ToastApi, ToastApiMessage, ToastApiMessageLink, ToastApiPostResult, TranslationApi, TranslationFunction, TranslationMessages, TranslationMessagesOptions, TranslationRef, TranslationRefOptions, TranslationResource, TranslationResourceOptions, TranslationSnapshot };