@backstage/core-plugin-api 0.1.13 → 0.3.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,60 @@
1
1
  # @backstage/core-plugin-api
2
2
 
3
+ ## 0.3.0
4
+
5
+ ### Minor Changes
6
+
7
+ - a036b65c2f: The `IdentityApi` has received several updates. The `getUserId`, `getProfile`, and `getIdToken` have all been deprecated.
8
+
9
+ The replacement for `getUserId` is the new `getBackstageIdentity` method, which provides both the `userEntityRef` as well as the `ownershipEntityRefs` that are used to resolve ownership. Existing usage of the user ID would typically be using a fixed entity kind and namespace, for example `` `user:default/${identityApi.getUserId()}` ``, this kind of usage should now instead use the `userEntityRef` directly.
10
+
11
+ The replacement for `getProfile` is the new async `getProfileInfo`.
12
+
13
+ The replacement for `getIdToken` is the new `getCredentials` method, which provides an optional token to the caller like before, but it is now wrapped in an object for forwards compatibility.
14
+
15
+ The deprecated `idToken` field of the `BackstageIdentity` type has been removed, leaving only the new `token` field, which should be used instead. The `BackstageIdentity` also received a new `identity` field, which is a decoded version of the information within the token. Furthermore the `BackstageIdentity` has been renamed to `BackstageIdentityResponse`, with the old name being deprecated.
16
+
17
+ We expect most of the breaking changes in this update to have low impact since the `IdentityApi` implementation is provided by the app, but it is likely that some tests need to be updated.
18
+
19
+ Another breaking change is that the `SignInPage` props have been updated, and the `SignInResult` type is now deprecated. This is unlikely to have any impact on the usage of this package, but it is an important change that you can find more information about in the [`@backstage/core-app-api` CHANGELOG.md](https://github.com/backstage/backstage/blob/master/packages/core-app-api/CHANGELOG.md).
20
+
21
+ ### Patch Changes
22
+
23
+ - cd450844f6: Moved React dependencies to `peerDependencies` and allow both React v16 and v17 to be used.
24
+ - dcd1a0c3f4: Minor improvement to the API reports, by not unpacking arguments directly
25
+ - Updated dependencies
26
+ - @backstage/version-bridge@0.1.1
27
+
28
+ ## 0.2.2
29
+
30
+ ### Patch Changes
31
+
32
+ - b291d0ed7e: Tweaked the logged deprecation warning for `createRouteRef` to hopefully make it more clear.
33
+ - bacb94ea8f: Documented the options of each of the extension creation functions.
34
+ - Updated dependencies
35
+ - @backstage/theme@0.2.14
36
+
37
+ ## 0.2.1
38
+
39
+ ### Patch Changes
40
+
41
+ - 950b36393c: Deprecated `register` option of `createPlugin` and the `outputs` methods of the plugin instance.
42
+
43
+ Introduces the `featureFlags` property to define your feature flags instead.
44
+
45
+ ## 0.2.0
46
+
47
+ ### Minor Changes
48
+
49
+ - 7e18ed7f29: Removed the unused `UserFlags` type.
50
+ - 7df99cdb77: Remove exports of unused types(`RouteOptions` and `RoutePath`).
51
+
52
+ ### Patch Changes
53
+
54
+ - 37ebea2d68: Add deprecation warnings around `title` `icon` and `path` as they are no longer controlled when creating `routeRefs`
55
+ - 2dd2a7b2cc: Deprecated the `theme` property on `AppTheme`, replacing it with `Provider`. See https://backstage.io/docs/api/deprecations#app-theme for more details.
56
+ - b6a4bacdc4: Deprecated the `Error` and `ErrorContext` types, replacing them with identical `ErrorApiError` and `ErrorApiErrorContext` types.
57
+
3
58
  ## 0.1.13
4
59
 
5
60
  ### Patch Changes
package/dist/index.d.ts CHANGED
@@ -4,6 +4,7 @@ import { Observable as Observable$1, Observer as Observer$1, Subscription as Sub
4
4
  import { BackstageTheme } from '@backstage/theme';
5
5
  import { Config } from '@backstage/config';
6
6
  import { SvgIconProps } from '@material-ui/core';
7
+ import { ProfileInfo as ProfileInfo$1, IdentityApi as IdentityApi$1, BackstagePlugin as BackstagePlugin$1, IconComponent as IconComponent$1 } from '@backstage/core-plugin-api';
7
8
 
8
9
  /**
9
10
  * Common analytics context attributes.
@@ -50,7 +51,7 @@ declare type AnalyticsContextValue = CommonAnalyticsContext & AnyAnalyticsContex
50
51
  *
51
52
  * @public
52
53
  */
53
- declare const AnalyticsContext: ({ attributes, children, }: {
54
+ declare const AnalyticsContext: (options: {
54
55
  attributes: Partial<AnalyticsContextValue>;
55
56
  children: ReactNode;
56
57
  }) => JSX.Element;
@@ -326,27 +327,57 @@ declare type BackstageIdentityApi = {
326
327
  * If the optional flag is not set, a session is guaranteed to be returned, while if
327
328
  * the optional flag is set, the session may be undefined. See {@link AuthRequestOptions} for more details.
328
329
  */
329
- getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentity | undefined>;
330
+ getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentityResponse | undefined>;
330
331
  };
331
332
  /**
332
- * A (user id, token) pair.
333
+ * User identity information within Backstage.
333
334
  *
334
335
  * @public
335
336
  */
336
- declare type BackstageIdentity = {
337
+ declare type BackstageUserIdentity = {
337
338
  /**
338
- * The backstage user ID.
339
+ * The type of identity that this structure represents. In the frontend app
340
+ * this will currently always be 'user'.
339
341
  */
340
- id: string;
342
+ type: 'user';
343
+ /**
344
+ * The entityRef of the user in the catalog.
345
+ * For example User:default/sandra
346
+ */
347
+ userEntityRef: string;
348
+ /**
349
+ * The user and group entities that the user claims ownership through
350
+ */
351
+ ownershipEntityRefs: string[];
352
+ };
353
+ /**
354
+ * Token and Identity response, with the users claims in the Identity.
355
+ *
356
+ * @public
357
+ */
358
+ declare type BackstageIdentityResponse = {
341
359
  /**
342
- * @deprecated This is deprecated, use `token` instead.
360
+ * The backstage user ID.
361
+ *
362
+ * @deprecated The identity is now provided via the `identity` field instead.
343
363
  */
344
- idToken: string;
364
+ id: string;
345
365
  /**
346
366
  * The token used to authenticate the user within Backstage.
347
367
  */
348
368
  token: string;
369
+ /**
370
+ * Identity information derived from the token.
371
+ */
372
+ identity: BackstageUserIdentity;
349
373
  };
374
+ /**
375
+ * The old exported symbol for {@link BackstageIdentityResponse}.
376
+ *
377
+ * @public
378
+ * @deprecated use {@link BackstageIdentityResponse} instead.
379
+ */
380
+ declare type BackstageIdentity = BackstageIdentityResponse;
350
381
  /**
351
382
  * Profile information of the user.
352
383
  *
@@ -666,12 +697,16 @@ declare type AppTheme = {
666
697
  variant: 'light' | 'dark';
667
698
  /**
668
699
  * The specialized MaterialUI theme instance.
700
+ * @deprecated use Provider instead, see https://backstage.io/docs/api/deprecations#app-theme
669
701
  */
670
702
  theme: BackstageTheme;
671
703
  /**
672
704
  * An Icon for the theme mode setting.
673
705
  */
674
706
  icon?: React.ReactElement;
707
+ Provider?(props: {
708
+ children: ReactNode;
709
+ }): JSX.Element | null;
675
710
  };
676
711
  /**
677
712
  * The AppThemeApi gives access to the current app theme, and allows switching
@@ -762,19 +797,29 @@ declare const discoveryApiRef: ApiRef<DiscoveryApi>;
762
797
  *
763
798
  * @public
764
799
  */
765
- declare type Error$1 = {
800
+ declare type ErrorApiError = {
766
801
  name: string;
767
802
  message: string;
768
803
  stack?: string;
769
804
  };
805
+ /**
806
+ * @public
807
+ * @deprecated Use ErrorApiError instead
808
+ */
809
+ declare type Error$1 = ErrorApiError;
770
810
  /**
771
811
  * Provides additional information about an error that was posted to the application.
772
812
  *
773
813
  * @public
774
814
  */
775
- declare type ErrorContext = {
815
+ declare type ErrorApiErrorContext = {
776
816
  hidden?: boolean;
777
817
  };
818
+ /**
819
+ * @public
820
+ * @deprecated Use ErrorApiErrorContext instead
821
+ */
822
+ declare type ErrorContext = ErrorApiErrorContext;
778
823
  /**
779
824
  * The error API is used to report errors to the app, and display them to the user.
780
825
  *
@@ -798,13 +843,13 @@ declare type ErrorApi = {
798
843
  /**
799
844
  * Post an error for handling by the application.
800
845
  */
801
- post(error: Error$1, context?: ErrorContext): void;
846
+ post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
802
847
  /**
803
848
  * Observe errors posted by other parts of the application.
804
849
  */
805
850
  error$(): Observable$1<{
806
- error: Error$1;
807
- context?: ErrorContext;
851
+ error: ErrorApiError;
852
+ context?: ErrorApiErrorContext;
808
853
  }>;
809
854
  };
810
855
  /**
@@ -855,12 +900,6 @@ declare type FeatureFlagsSaveOptions = {
855
900
  */
856
901
  merge?: boolean;
857
902
  };
858
- /**
859
- * User flags alias.
860
- *
861
- * @public
862
- */
863
- declare type UserFlags = {};
864
903
  /**
865
904
  * The feature flags API is used to toggle functionality to users across plugins and Backstage.
866
905
  *
@@ -912,22 +951,41 @@ declare type IdentityApi = {
912
951
  * The ID of the signed in user. This ID is not meant to be presented to the user, but used
913
952
  * as an opaque string to pass on to backends or use in frontend logic.
914
953
  *
915
- * TODO: The intention of the user ID is to be able to tie the user to an identity
916
- * that is known by the catalog and/or identity backend. It should for example
917
- * be possible to fetch all owned components using this ID.
954
+ * @deprecated use {@link IdentityApi.getBackstageIdentity} instead.
918
955
  */
919
956
  getUserId(): string;
957
+ /**
958
+ * An OpenID Connect ID Token which proves the identity of the signed in user.
959
+ *
960
+ * The ID token will be undefined if the signed in user does not have a verified
961
+ * identity, such as a demo user or mocked user for e2e tests.
962
+ *
963
+ * @deprecated use {@link IdentityApi.getCredentials} instead.
964
+ */
965
+ getIdToken(): Promise<string | undefined>;
920
966
  /**
921
967
  * The profile of the signed in user.
968
+ *
969
+ * @deprecated use {@link IdentityApi.getProfileInfo} instead.
922
970
  */
923
971
  getProfile(): ProfileInfo;
924
972
  /**
925
- * An OpenID Connect ID Token which proves the identity of the signed in user.
973
+ * The profile of the signed in user.
974
+ */
975
+ getProfileInfo(): Promise<ProfileInfo>;
976
+ /**
977
+ * User identity information within Backstage.
978
+ */
979
+ getBackstageIdentity(): Promise<BackstageUserIdentity>;
980
+ /**
981
+ * Provides credentials in the form of a token which proves the identity of the signed in user.
926
982
  *
927
- * The ID token will be undefined if the signed in user does not have a verified
983
+ * The token will be undefined if the signed in user does not have a verified
928
984
  * identity, such as a demo user or mocked user for e2e tests.
929
985
  */
930
- getIdToken(): Promise<string | undefined>;
986
+ getCredentials(): Promise<{
987
+ token?: string;
988
+ }>;
931
989
  /**
932
990
  * Sign out the current user
933
991
  */
@@ -1143,6 +1201,135 @@ declare const storageApiRef: ApiRef<StorageApi>;
1143
1201
  */
1144
1202
  declare function useAnalytics(): AnalyticsTracker;
1145
1203
 
1204
+ /**
1205
+ * Props for the `BootErrorPage` component of {@link AppComponents}.
1206
+ *
1207
+ * @public
1208
+ */
1209
+ declare type BootErrorPageProps = {
1210
+ step: 'load-config' | 'load-chunk';
1211
+ error: Error;
1212
+ };
1213
+ /**
1214
+ * The outcome of signing in on the sign-in page.
1215
+ *
1216
+ * @public
1217
+ * @deprecated replaced by passing the {@link @backstage/core-plugin-api#IdentityApi} to the {@link SignInPageProps.onSignInSuccess} instead.
1218
+ */
1219
+ declare type SignInResult = {
1220
+ /**
1221
+ * User ID that will be returned by the IdentityApi
1222
+ */
1223
+ userId: string;
1224
+ profile: ProfileInfo$1;
1225
+ /**
1226
+ * Function used to retrieve an ID token for the signed in user.
1227
+ */
1228
+ getIdToken?: () => Promise<string>;
1229
+ /**
1230
+ * Sign out handler that will be called if the user requests to sign out.
1231
+ */
1232
+ signOut?: () => Promise<void>;
1233
+ };
1234
+ /**
1235
+ * Props for the `SignInPage` component of {@link AppComponents}.
1236
+ *
1237
+ * @public
1238
+ */
1239
+ declare type SignInPageProps = {
1240
+ /**
1241
+ * Set the IdentityApi on successful sign in. This should only be called once.
1242
+ */
1243
+ onSignInSuccess(identityApi: IdentityApi$1): void;
1244
+ };
1245
+ /**
1246
+ * Props for the fallback error boundary.
1247
+ *
1248
+ * @public
1249
+ */
1250
+ declare type ErrorBoundaryFallbackProps = {
1251
+ plugin?: BackstagePlugin$1;
1252
+ error: Error;
1253
+ resetError: () => void;
1254
+ };
1255
+ /**
1256
+ * A set of replaceable core components that are part of every Backstage app.
1257
+ *
1258
+ * @public
1259
+ */
1260
+ declare type AppComponents = {
1261
+ NotFoundErrorPage: ComponentType<{}>;
1262
+ BootErrorPage: ComponentType<BootErrorPageProps>;
1263
+ Progress: ComponentType<{}>;
1264
+ Router: ComponentType<{}>;
1265
+ ErrorBoundaryFallback: ComponentType<ErrorBoundaryFallbackProps>;
1266
+ ThemeProvider?: ComponentType<{}>;
1267
+ /**
1268
+ * An optional sign-in page that will be rendered instead of the AppRouter at startup.
1269
+ *
1270
+ * If a sign-in page is set, it will always be shown before the app, and it is up
1271
+ * to the sign-in page to handle e.g. saving of login methods for subsequent visits.
1272
+ *
1273
+ * The sign-in page will be displayed until it has passed up a result to the parent,
1274
+ * and which point the AppRouter and all of its children will be rendered instead.
1275
+ */
1276
+ SignInPage?: ComponentType<SignInPageProps>;
1277
+ };
1278
+ /**
1279
+ * The central context providing runtime app specific state that plugin views
1280
+ * want to consume.
1281
+ *
1282
+ * @public
1283
+ */
1284
+ declare type AppContext = {
1285
+ /**
1286
+ * Get a list of all plugins that are installed in the app.
1287
+ */
1288
+ getPlugins(): BackstagePlugin$1<any, any>[];
1289
+ /**
1290
+ * Get a common or custom icon for this app.
1291
+ */
1292
+ getSystemIcon(key: string): IconComponent$1 | undefined;
1293
+ /**
1294
+ * Get the components registered for various purposes in the app.
1295
+ */
1296
+ getComponents(): AppComponents;
1297
+ };
1298
+
1299
+ /**
1300
+ * React hook providing {@link AppContext}.
1301
+ *
1302
+ * @public
1303
+ */
1304
+ declare const useApp: () => AppContext;
1305
+
1306
+ /**
1307
+ * Stores data related to a component in a global store.
1308
+ *
1309
+ * @remarks
1310
+ *
1311
+ * See {@link https://backstage.io/docs/plugins/composability#component-data}.
1312
+ *
1313
+ * @param component - The component to attach the data to.
1314
+ * @param type - The key under which the data will be stored.
1315
+ * @param data - Arbitrary value.
1316
+ * @public
1317
+ */
1318
+ declare function attachComponentData<P>(component: ComponentType<P>, type: string, data: unknown): void;
1319
+ /**
1320
+ * Retrieves data attached to a component.
1321
+ *
1322
+ * @remarks
1323
+ *
1324
+ * See {@link https://backstage.io/docs/plugins/composability#component-data}.
1325
+ *
1326
+ * @param node - React component to look up.
1327
+ * @param type - Key of the data to retrieve.
1328
+ * @returns Data stored using {@link attachComponentData}.
1329
+ * @public
1330
+ */
1331
+ declare function getComponentData<T>(node: ReactNode, type: string): T | undefined;
1332
+
1146
1333
  /**
1147
1334
  * Catch-all type for route params.
1148
1335
  *
@@ -1357,23 +1544,9 @@ declare function useRouteRef<Params extends AnyParams>(routeRef: RouteRef<Params
1357
1544
  */
1358
1545
  declare function useRouteRefParams<Params extends AnyParams>(_routeRef: RouteRef<Params> | SubRouteRef<Params>): Params;
1359
1546
 
1360
- /**
1361
- * Route configuration.
1362
- *
1363
- * @public
1364
- */
1365
- declare type RouteOptions = {
1366
- exact?: boolean;
1367
- };
1368
- /**
1369
- * Type alias for paths.
1370
- *
1371
- * @public
1372
- */
1373
- declare type RoutePath = string;
1374
1547
  /**
1375
1548
  * Replace with using {@link RouteRef}s.
1376
- *
1549
+ * @deprecated will be removed
1377
1550
  * @public
1378
1551
  */
1379
1552
  declare type FeatureFlagOutput = {
@@ -1384,6 +1557,7 @@ declare type FeatureFlagOutput = {
1384
1557
  * {@link FeatureFlagOutput} type.
1385
1558
  *
1386
1559
  * @public
1560
+ * @deprecated Use {@link BackstagePlugin.getFeatureFlags} instead.
1387
1561
  */
1388
1562
  declare type PluginOutput = FeatureFlagOutput;
1389
1563
  /**
@@ -1421,12 +1595,28 @@ declare type AnyExternalRoutes = {
1421
1595
  */
1422
1596
  declare type BackstagePlugin<Routes extends AnyRoutes = {}, ExternalRoutes extends AnyExternalRoutes = {}> = {
1423
1597
  getId(): string;
1598
+ /**
1599
+ * @deprecated use getFeatureFlags instead.
1600
+ * */
1424
1601
  output(): PluginOutput[];
1425
1602
  getApis(): Iterable<AnyApiFactory>;
1603
+ /**
1604
+ * Returns all registered feature flags for this plugin.
1605
+ */
1606
+ getFeatureFlags(): Iterable<PluginFeatureFlagConfig>;
1426
1607
  provide<T>(extension: Extension<T>): T;
1427
1608
  routes: Routes;
1428
1609
  externalRoutes: ExternalRoutes;
1429
1610
  };
1611
+ /**
1612
+ * Plugin feature flag configuration.
1613
+ *
1614
+ * @public
1615
+ */
1616
+ declare type PluginFeatureFlagConfig = {
1617
+ /** Feature flag name */
1618
+ name: string;
1619
+ };
1430
1620
  /**
1431
1621
  * Plugin descriptor type.
1432
1622
  *
@@ -1435,13 +1625,16 @@ declare type BackstagePlugin<Routes extends AnyRoutes = {}, ExternalRoutes exten
1435
1625
  declare type PluginConfig<Routes extends AnyRoutes, ExternalRoutes extends AnyExternalRoutes> = {
1436
1626
  id: string;
1437
1627
  apis?: Iterable<AnyApiFactory>;
1628
+ /** @deprecated use featureFlags property instead for defining feature flags */
1438
1629
  register?(hooks: PluginHooks): void;
1439
1630
  routes?: Routes;
1440
1631
  externalRoutes?: ExternalRoutes;
1632
+ featureFlags?: PluginFeatureFlagConfig[];
1441
1633
  };
1442
1634
  /**
1443
1635
  * Holds hooks registered by the plugin.
1444
1636
  *
1637
+ * @deprecated - feature flags are now registered in plugin config under featureFlags
1445
1638
  * @public
1446
1639
  */
1447
1640
  declare type PluginHooks = {
@@ -1456,132 +1649,6 @@ declare type FeatureFlagsHooks = {
1456
1649
  register(name: string): void;
1457
1650
  };
1458
1651
 
1459
- /**
1460
- * Props for the BootErrorPage.
1461
- *
1462
- * @public
1463
- */
1464
- declare type BootErrorPageProps = {
1465
- step: 'load-config' | 'load-chunk';
1466
- error: Error;
1467
- };
1468
- /**
1469
- * Data and handlers associated with the user sign in event.
1470
- *
1471
- * @public
1472
- */
1473
- declare type SignInResult = {
1474
- /**
1475
- * User ID that will be returned by the IdentityApi
1476
- */
1477
- userId: string;
1478
- profile: ProfileInfo;
1479
- /**
1480
- * Function used to retrieve an ID token for the signed in user.
1481
- */
1482
- getIdToken?: () => Promise<string>;
1483
- /**
1484
- * Sign out handler that will be called if the user requests to sign out.
1485
- */
1486
- signOut?: () => Promise<void>;
1487
- };
1488
- /**
1489
- * Props for the SignInPage.
1490
- *
1491
- * @public
1492
- */
1493
- declare type SignInPageProps = {
1494
- /**
1495
- * Set the sign-in result for the app. This should only be called once.
1496
- */
1497
- onResult(result: SignInResult): void;
1498
- };
1499
- /**
1500
- * Props for the ErrorBoundaryFallback.
1501
- *
1502
- * @public
1503
- */
1504
- declare type ErrorBoundaryFallbackProps = {
1505
- plugin?: BackstagePlugin;
1506
- error: Error;
1507
- resetError: () => void;
1508
- };
1509
- /**
1510
- * Basic app components.
1511
- *
1512
- * @public
1513
- */
1514
- declare type AppComponents = {
1515
- NotFoundErrorPage: ComponentType<{}>;
1516
- BootErrorPage: ComponentType<BootErrorPageProps>;
1517
- Progress: ComponentType<{}>;
1518
- Router: ComponentType<{}>;
1519
- ErrorBoundaryFallback: ComponentType<ErrorBoundaryFallbackProps>;
1520
- /**
1521
- * An optional sign-in page that will be rendered instead of the AppRouter at startup.
1522
- *
1523
- * If a sign-in page is set, it will always be shown before the app, and it is up
1524
- * to the sign-in page to handle e.g. saving of login methods for subsequent visits.
1525
- *
1526
- * The sign-in page will be displayed until it has passed up a result to the parent,
1527
- * and which point the AppRouter and all of its children will be rendered instead.
1528
- */
1529
- SignInPage?: ComponentType<SignInPageProps>;
1530
- };
1531
- /**
1532
- * Provides plugins and components registered in the app.
1533
- *
1534
- * @public
1535
- */
1536
- declare type AppContext = {
1537
- /**
1538
- * Get a list of all plugins that are installed in the app.
1539
- */
1540
- getPlugins(): BackstagePlugin<any, any>[];
1541
- /**
1542
- * Get a common or custom icon for this app.
1543
- */
1544
- getSystemIcon(key: string): IconComponent | undefined;
1545
- /**
1546
- * Get the components registered for various purposes in the app.
1547
- */
1548
- getComponents(): AppComponents;
1549
- };
1550
-
1551
- /**
1552
- * React hook providing {@link AppContext}.
1553
- *
1554
- * @public
1555
- */
1556
- declare const useApp: () => AppContext;
1557
-
1558
- /**
1559
- * Stores data related to a component in a global store.
1560
- *
1561
- * @remarks
1562
- *
1563
- * See {@link https://backstage.io/docs/plugins/composability#component-data}.
1564
- *
1565
- * @param component - The component to attach the data to.
1566
- * @param type - The key under which the data will be stored.
1567
- * @param data - Arbitrary value.
1568
- * @public
1569
- */
1570
- declare function attachComponentData<P>(component: ComponentType<P>, type: string, data: unknown): void;
1571
- /**
1572
- * Retrieves data attached to a component.
1573
- *
1574
- * @remarks
1575
- *
1576
- * See {@link https://backstage.io/docs/plugins/composability#component-data}.
1577
- *
1578
- * @param node - React component to look up.
1579
- * @param type - Key of the data to retrieve.
1580
- * @returns Data stored using {@link attachComponentData}.
1581
- * @public
1582
- */
1583
- declare function getComponentData<T>(node: ReactNode, type: string): T | undefined;
1584
-
1585
1652
  /**
1586
1653
  * Lazy or synchronous retrieving of extension components.
1587
1654
  *
@@ -1606,8 +1673,25 @@ declare type ComponentLoader<T> = {
1606
1673
  * @public
1607
1674
  */
1608
1675
  declare function createRoutableExtension<T extends (props: any) => JSX.Element | null>(options: {
1676
+ /**
1677
+ * A loader for the component that is rendered by this extension.
1678
+ */
1609
1679
  component: () => Promise<T>;
1680
+ /**
1681
+ * The mount point to bind this routable extension to.
1682
+ *
1683
+ * If this extension is placed somewhere in the app element tree of a Backstage
1684
+ * app, callers will be able to route to this extensions by calling,
1685
+ * `useRouteRef` with this mount point.
1686
+ */
1610
1687
  mountPoint: RouteRef;
1688
+ /**
1689
+ * The name of this extension that will represent it at runtime. It is for example
1690
+ * used to identify this extension in analytics data.
1691
+ *
1692
+ * If possible the name should always be the same as the name of the exported
1693
+ * variable for this extension.
1694
+ */
1611
1695
  name?: string;
1612
1696
  }): Extension<T>;
1613
1697
  /**
@@ -1624,7 +1708,17 @@ declare function createRoutableExtension<T extends (props: any) => JSX.Element |
1624
1708
  * @public
1625
1709
  */
1626
1710
  declare function createComponentExtension<T extends (props: any) => JSX.Element | null>(options: {
1711
+ /**
1712
+ * A loader or synchronously supplied component that is rendered by this extension.
1713
+ */
1627
1714
  component: ComponentLoader<T>;
1715
+ /**
1716
+ * The name of this extension that will represent it at runtime. It is for example
1717
+ * used to identify this extension in analytics data.
1718
+ *
1719
+ * If possible the name should always be the same as the name of the exported
1720
+ * variable for this extension.
1721
+ */
1628
1722
  name?: string;
1629
1723
  }): Extension<T>;
1630
1724
  /**
@@ -1641,8 +1735,21 @@ declare function createComponentExtension<T extends (props: any) => JSX.Element
1641
1735
  * @public
1642
1736
  */
1643
1737
  declare function createReactExtension<T extends (props: any) => JSX.Element | null>(options: {
1738
+ /**
1739
+ * A loader or synchronously supplied component that is rendered by this extension.
1740
+ */
1644
1741
  component: ComponentLoader<T>;
1742
+ /**
1743
+ * Additional component data that is attached to the top-level extension component.
1744
+ */
1645
1745
  data?: Record<string, unknown>;
1746
+ /**
1747
+ * The name of this extension that will represent it at runtime. It is for example
1748
+ * used to identify this extension in analytics data.
1749
+ *
1750
+ * If possible the name should always be the same as the name of the exported
1751
+ * variable for this extension.
1752
+ */
1646
1753
  name?: string;
1647
1754
  }): Extension<T>;
1648
1755
 
@@ -1761,4 +1868,4 @@ declare type Subscription = Subscription$1;
1761
1868
  */
1762
1869
  declare type Observable<T> = Observable$1<T>;
1763
1870
 
1764
- export { AlertApi, AlertMessage, AnalyticsApi, AnalyticsContext, AnalyticsContextValue, AnalyticsEvent, AnalyticsEventAttributes, AnalyticsTracker, AnyAnalyticsContext, AnyApiFactory, AnyApiRef, AnyExternalRoutes, AnyParams, AnyRoutes, ApiFactory, ApiHolder, ApiRef, ApiRefConfig, ApiRefType, ApiRefsToTypes, AppComponents, AppContext, AppTheme, AppThemeApi, AuthProvider, AuthRequestOptions, AuthRequester, AuthRequesterOptions, BackstageIdentity, BackstageIdentityApi, BackstagePlugin, BootErrorPageProps, CommonAnalyticsContext, ComponentLoader, ConfigApi, DiscoveryApi, ElementCollection, Error$1 as Error, ErrorApi, ErrorBoundaryFallbackProps, ErrorContext, Extension, ExternalRouteRef, FeatureFlag, FeatureFlagOutput, FeatureFlagState, FeatureFlagsApi, FeatureFlagsHooks, FeatureFlagsSaveOptions, IconComponent, IdentityApi, MakeSubRouteRef, MergeParams, OAuthApi, OAuthRequestApi, OAuthScope, Observable, Observer, OldIconComponent, OpenIdConnectApi, OptionalParams, ParamKeys, ParamNames, ParamPart, PathParams, PendingAuthRequest, PluginConfig, PluginHooks, PluginOutput, ProfileInfo, ProfileInfoApi, RouteFunc, RouteOptions, RoutePath, RouteRef, SessionApi, SessionState, SignInPageProps, SignInResult, StorageApi, StorageValueChange, SubRouteRef, Subscription, TypesToApiRefs, UserFlags, alertApiRef, analyticsApiRef, appThemeApiRef, atlassianAuthApiRef, attachComponentData, auth0AuthApiRef, bitbucketAuthApiRef, configApiRef, createApiFactory, createApiRef, createComponentExtension, createExternalRouteRef, createPlugin, createReactExtension, createRoutableExtension, createRouteRef, createSubRouteRef, discoveryApiRef, errorApiRef, featureFlagsApiRef, getComponentData, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, identityApiRef, microsoftAuthApiRef, oauth2ApiRef, oauthRequestApiRef, oidcAuthApiRef, oktaAuthApiRef, oneloginAuthApiRef, samlAuthApiRef, storageApiRef, useAnalytics, useApi, useApiHolder, useApp, useElementFilter, useRouteRef, useRouteRefParams, withApis };
1871
+ export { AlertApi, AlertMessage, AnalyticsApi, AnalyticsContext, AnalyticsContextValue, AnalyticsEvent, AnalyticsEventAttributes, AnalyticsTracker, AnyAnalyticsContext, AnyApiFactory, AnyApiRef, AnyExternalRoutes, AnyParams, AnyRoutes, ApiFactory, ApiHolder, ApiRef, ApiRefConfig, ApiRefType, ApiRefsToTypes, AppComponents, AppContext, AppTheme, AppThemeApi, AuthProvider, AuthRequestOptions, AuthRequester, AuthRequesterOptions, BackstageIdentity, BackstageIdentityApi, BackstageIdentityResponse, BackstagePlugin, BackstageUserIdentity, BootErrorPageProps, CommonAnalyticsContext, ComponentLoader, ConfigApi, DiscoveryApi, ElementCollection, Error$1 as Error, ErrorApi, ErrorApiError, ErrorApiErrorContext, ErrorBoundaryFallbackProps, ErrorContext, Extension, ExternalRouteRef, FeatureFlag, FeatureFlagOutput, FeatureFlagState, FeatureFlagsApi, FeatureFlagsHooks, FeatureFlagsSaveOptions, IconComponent, IdentityApi, MakeSubRouteRef, MergeParams, OAuthApi, OAuthRequestApi, OAuthScope, Observable, Observer, OldIconComponent, OpenIdConnectApi, OptionalParams, ParamKeys, ParamNames, ParamPart, PathParams, PendingAuthRequest, PluginConfig, PluginFeatureFlagConfig, PluginHooks, PluginOutput, ProfileInfo, ProfileInfoApi, RouteFunc, RouteRef, SessionApi, SessionState, SignInPageProps, SignInResult, StorageApi, StorageValueChange, SubRouteRef, Subscription, TypesToApiRefs, alertApiRef, analyticsApiRef, appThemeApiRef, atlassianAuthApiRef, attachComponentData, auth0AuthApiRef, bitbucketAuthApiRef, configApiRef, createApiFactory, createApiRef, createComponentExtension, createExternalRouteRef, createPlugin, createReactExtension, createRoutableExtension, createRouteRef, createSubRouteRef, discoveryApiRef, errorApiRef, featureFlagsApiRef, getComponentData, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, identityApiRef, microsoftAuthApiRef, oauth2ApiRef, oauthRequestApiRef, oidcAuthApiRef, oktaAuthApiRef, oneloginAuthApiRef, samlAuthApiRef, storageApiRef, useAnalytics, useApi, useApiHolder, useApp, useElementFilter, useRouteRef, useRouteRefParams, withApis };