Merge pull request #30839 from backstage/blam/backwards-compat-swap

Backwards compatibility of `componentsApi` and `SwappableComponents`

.changeset/component-refs-app.md

@@ -3,3 +3,5 @@
 ---
 
 Default implementations of core components are now provided by this package.
+
+A backwards compatible `componentsApi` implementation is also provided from this package which uses the `SwappableComponentsApi` as the implementation. This backwards compatible wrapper will be removed in the future.

.changeset/fuzzy-ducks-jump.md

@@ -1,5 +1,5 @@
 ---
-'@backstage/core-compat-api': minor
+'@backstage/core-compat-api': patch
 ---
 
-**BREAKING**: The `componentsApi` implementation has been removed from the plugin and replaced with the new `SwappableComponentsApi` instead. Which means that the `componentsApi` is not longer backwards compatible with legacy plugins.
+The `compatWrapper` has been switched to use the new `SwappableComponentsApi` instead of the old `ComponentsApi` in its bridging to the old frontend system.

packages/frontend-defaults/src/createApp.test.tsx

@@ -392,6 +392,7 @@ describe('createApp', () => {
           <api:app/icons out=[core.api.factory] />
           <api:app/feature-flags out=[core.api.factory] />
           <api:app/translations out=[core.api.factory] />
+          <api:app/components out=[core.api.factory] />
         ]
         app [
           <app out=[core.reactElement]>

plugins/app/package.json

@@ -25,6 +25,8 @@
     "./alpha": "./src/alpha/index.ts",
     "./package.json": "./package.json"
   },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "typesVersions": {
     "*": {
       "alpha": [
@@ -35,8 +37,6 @@
       ]
     }
   },
-  "main": "src/index.ts",
-  "types": "src/index.ts",
   "files": [
     "dist"
   ],
@@ -57,11 +57,13 @@
     "@backstage/plugin-permission-react": "workspace:^",
     "@backstage/theme": "workspace:^",
     "@backstage/types": "workspace:^",
+    "@backstage/version-bridge": "workspace:^",
     "@material-ui/core": "^4.9.13",
     "@material-ui/icons": "^4.9.1",
     "@material-ui/lab": "^4.0.0-alpha.61",
     "@react-hookz/web": "^24.0.0",
-    "react-use": "^17.2.4"
+    "react-use": "^17.2.4",
+    "zod": "^3.22.4"
   },
   "devDependencies": {
     "@backstage/cli": "workspace:^",

plugins/app/report.api.md

@@ -315,6 +315,21 @@ const appPlugin: FrontendPlugin<
         params: ApiFactory<TApi, TImpl, TDeps>,
       ) => ExtensionBlueprintParams<AnyApiFactory>;
     }>;
+    'api:app/components': ExtensionDefinition<{
+      kind: 'api';
+      name: 'components';
+      config: {};
+      configInput: {};
+      output: ExtensionDataRef<AnyApiFactory, 'core.api.factory', {}>;
+      inputs: {};
+      params: <
+        TApi,
+        TImpl extends TApi,
+        TDeps extends { [name in string]: unknown },
+      >(
+        params: ApiFactory<TApi, TImpl, TDeps>,
+      ) => ExtensionBlueprintParams<AnyApiFactory>;
+    }>;
     'api:app/dialog': ExtensionDefinition<{
       kind: 'api';
       name: 'dialog';

plugins/app/src/extensions/LegacyComponentsApi.ts

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  ApiBlueprint,
+  createApiRef,
+  ErrorDisplay,
+  NotFoundErrorPage,
+  Progress,
+} from '@backstage/frontend-plugin-api';
+import { ComponentType } from 'react';
+
+/**
+ * This is the old component API that has been replaced by the new SwappableComponentsApi.
+ *
+ * This backwards compatibility implementation exists to avoid breaking older plugins.
+ *
+ * This was added for the 1.42 release, and can be removed in the future.
+ *
+ * @internal
+ */
+export const LegacyComponentsApi = ApiBlueprint.make({
+  name: 'components',
+  params: defineParams =>
+    defineParams({
+      api: createApiRef<{
+        getComponent(ref: { id: string }): ComponentType<any>;
+      }>({ id: 'core.components' }),
+      deps: {},
+      factory: () => ({
+        getComponent(ref) {
+          if (ref.id === 'core.components.progress') {
+            return Progress;
+          }
+          if (ref.id === 'core.components.notFoundErrorPage') {
+            return NotFoundErrorPage;
+          }
+          if (ref.id === 'core.components.errorBoundaryFallback') {
+            return ErrorDisplay;
+          }
+          throw new Error(`No implementation found for component ref ${ref}`);
+        },
+      }),
+    }),
+});

plugins/app/src/extensions/SwappableComponentsApi.ts

@@ -20,8 +20,7 @@ import {
   ApiBlueprint,
   swappableComponentsApiRef,
 } from '@backstage/frontend-plugin-api';
-// eslint-disable-next-line @backstage/no-relative-monorepo-imports
-import { DefaultSwappableComponentsApi } from '../../../../packages/frontend-app-api/src/apis/implementations/SwappableComponentsApi';
+import { DefaultSwappableComponentsApi } from '../apis/SwappableComponentsApi';
 
 /**
  * Contains the shareable components installed into the app.

plugins/app/src/extensions/index.ts

@@ -21,6 +21,7 @@ export { AppRoot } from './AppRoot';
 export { AppRoutes } from './AppRoutes';
 export { AppThemeApi, DarkTheme, LightTheme } from './AppThemeApi';
 export { SwappableComponentsApi } from './SwappableComponentsApi';
+export { LegacyComponentsApi } from './LegacyComponentsApi';
 export { IconsApi } from './IconsApi';
 export { FeatureFlagsApi } from './FeatureFlagsApi';
 export { TranslationsApi } from './TranslationsApi';

plugins/app/src/plugin.ts

@@ -36,6 +36,7 @@ import {
   Progress,
   NotFoundErrorPage,
   ErrorBoundary,
+  LegacyComponentsApi,
 } from './extensions';
 import { apis } from './defaultApis';
 
@@ -65,5 +66,6 @@ export const appPlugin = createFrontendPlugin({
     Progress,
     NotFoundErrorPage,
     ErrorBoundary,
+    LegacyComponentsApi,
   ],
 });

yarn.lock

@@ -3835,6 +3835,7 @@ __metadata:
     "@backstage/test-utils": "workspace:^"
     "@backstage/theme": "workspace:^"
     "@backstage/types": "workspace:^"
+    "@backstage/version-bridge": "workspace:^"
     "@material-ui/core": "npm:^4.9.13"
     "@material-ui/icons": "npm:^4.9.1"
     "@material-ui/lab": "npm:^4.0.0-alpha.61"
@@ -3848,6 +3849,7 @@ __metadata:
     react-dom: "npm:^18.0.2"
     react-router-dom: "npm:^6.3.0"
     react-use: "npm:^17.2.4"
+    zod: "npm:^3.22.4"
   peerDependencies:
     "@types/react": ^17.0.0 || ^18.0.0
     react: ^17.0.0 || ^18.0.0