frontend-plugin-api: add createExtensionOverrides

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/silly-chefs-allow.md

@@ -0,0 +1,5 @@
+---
+'@backstage/frontend-plugin-api': patch
+---
+
+Added `createExtensionOverrides` which can be used to install a collection of extensions in an app that will replace any existing ones.

packages/frontend-plugin-api/api-report.md

@@ -159,6 +159,11 @@ export interface CreateExtensionOptions<
   output: TOutput;
 }
 
+// @public (undocumented)
+export function createExtensionOverrides(
+  options: ExtensionOverridesOptions,
+): ExtensionOverrides;
+
 // @public
 export function createNavItemExtension(options: {
   id: string;
@@ -313,6 +318,18 @@ export type ExtensionInputValues<
       >;
 };
 
+// @public (undocumented)
+export interface ExtensionOverrides {
+  // (undocumented)
+  $$type: '@backstage/ExtensionOverrides';
+}
+
+// @public (undocumented)
+export interface ExtensionOverridesOptions {
+  // (undocumented)
+  extensions: Extension<unknown>[];
+}
+
 // @public (undocumented)
 export type NavTarget = {
   title: string;

packages/frontend-plugin-api/src/wiring/createExtensionOverrides.test.ts

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2023 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 { createExtension } from './createExtension';
+import {
+  createExtensionOverrides,
+  toInternalExtensionOverrides,
+} from './createExtensionOverrides';
+
+describe('createExtensionOverrides', () => {
+  it('should create overrides without extensions', () => {
+    expect(createExtensionOverrides({ extensions: [] })).toMatchInlineSnapshot(`
+      {
+        "$$type": "@backstage/ExtensionOverrides",
+        "extensions": [],
+        "version": "v1",
+      }
+    `);
+  });
+
+  it('should create overrides with extensions', () => {
+    expect(
+      createExtensionOverrides({
+        extensions: [
+          createExtension({
+            id: 'a',
+            attachTo: { id: 'core', input: 'apis' },
+            output: {},
+            factory() {},
+          }),
+        ],
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "$$type": "@backstage/ExtensionOverrides",
+        "extensions": [
+          {
+            "$$type": "@backstage/Extension",
+            "attachTo": {
+              "id": "core",
+              "input": "apis",
+            },
+            "disabled": false,
+            "factory": [Function],
+            "id": "a",
+            "inputs": {},
+            "output": {},
+          },
+        ],
+        "version": "v1",
+      }
+    `);
+  });
+
+  it('should convert to internal overrides', () => {
+    const overrides = createExtensionOverrides({
+      extensions: [
+        createExtension({
+          id: 'a',
+          attachTo: { id: 'core', input: 'apis' },
+          output: {},
+          factory() {},
+        }),
+      ],
+    });
+    const internal = toInternalExtensionOverrides(overrides);
+    expect(internal).toBe(overrides);
+  });
+});

packages/frontend-plugin-api/src/wiring/createExtensionOverrides.ts

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2023 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 { Extension } from './createExtension';
+
+/** @public */
+export interface ExtensionOverridesOptions {
+  extensions: Extension<unknown>[];
+}
+
+/** @public */
+export interface ExtensionOverrides {
+  $$type: '@backstage/ExtensionOverrides';
+}
+
+/** @internal */
+export interface InternalExtensionOverrides extends ExtensionOverrides {
+  version: string;
+  extensions: Extension<unknown>[];
+}
+
+/** @public */
+export function createExtensionOverrides(
+  options: ExtensionOverridesOptions,
+): ExtensionOverrides {
+  return {
+    $$type: '@backstage/ExtensionOverrides',
+    version: 'v1',
+    extensions: options.extensions,
+  } as InternalExtensionOverrides;
+}
+
+/** @internal */
+export function toInternalExtensionOverrides(
+  overrides: ExtensionOverrides,
+): InternalExtensionOverrides {
+  const internal = overrides as InternalExtensionOverrides;
+  if (internal.$$type !== '@backstage/ExtensionOverrides') {
+    throw new Error(
+      `Invalid translation resource, bad type '${internal.$$type}'`,
+    );
+  }
+  if (internal.version !== 'v1') {
+    throw new Error(
+      `Invalid translation resource, bad version '${internal.version}'`,
+    );
+  }
+  return internal;
+}

packages/frontend-plugin-api/src/wiring/index.ts

@@ -38,3 +38,8 @@ export {
   type BackstagePlugin,
   type PluginOptions,
 } from './createPlugin';
+export {
+  createExtensionOverrides,
+  type ExtensionOverrides,
+  type ExtensionOverridesOptions,
+} from './createExtensionOverrides';