From cc6ccb5e11c61a7f4eeaff4ee90638793850f338 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Fri, 15 Dec 2023 15:41:28 +0100 Subject: [PATCH] review fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .../architecture/06-utility-apis.md | 2 +- .../utility-apis/03-consuming.md | 4 +-- .../utility-apis/04-configuring.md | 29 ++++++++-------- .../utility-apis/05-migrating.md | 34 +++++-------------- 4 files changed, 26 insertions(+), 43 deletions(-) diff --git a/docs/frontend-system/architecture/06-utility-apis.md b/docs/frontend-system/architecture/06-utility-apis.md index ff106e2ea6..c0b65a840b 100644 --- a/docs/frontend-system/architecture/06-utility-apis.md +++ b/docs/frontend-system/architecture/06-utility-apis.md @@ -14,7 +14,7 @@ Utility APIs are pieces of standalone functionality, interfaces that can be requ A common example of a utility API is a client interface to interact with the backend part of a plugin, such as the catalog client. Any frontend plugin can then request an implementation of that interface to make requests through. -The following diagram shows a hypothetical application, which depends on two plugins and also provides some extra overrides. Note that both the plugins and the core framework provide utility APIs, and that they depended on each other. The app also choses to use its overrides mechanism to supply a replacement implementation of one API, which takes precedence over the default one. Thus, all consumers of that API will be sure to get that new implementation provided to them. +The following diagram shows a hypothetical application, which depends on two plugins and also provides some extra overrides. Note that both the plugins and the core framework provide utility APIs, and that they depended on each other. The app also chooses to use its overrides mechanism to supply a replacement implementation of one API, which takes precedence over the default one. Thus, all consumers of that API will be sure to get that new implementation provided to them. ![frontend system utility apis diagram](../../assets/frontend-system/architecture-utility-apis.drawio.svg) diff --git a/docs/frontend-system/utility-apis/03-consuming.md b/docs/frontend-system/utility-apis/03-consuming.md index 006f3b8fab..4748cc786a 100644 --- a/docs/frontend-system/utility-apis/03-consuming.md +++ b/docs/frontend-system/utility-apis/03-consuming.md @@ -17,7 +17,7 @@ import { useApi, configApiRef } from '@backstage/frontend-plugin-api'; const MyComponent = () => { const configApi = useApi(configApiRef); - const baseUrl = configApi.getString('backend.baseUrl'); + const title = configApi.getString('app.title'); // ... }; ``` @@ -31,7 +31,7 @@ const MyComponent = () => { const apis = useApiHolder(); const configApi = apis.get(configApiRef); // may return undefined if (configApi) { - const baseUrl = configApi.getString('backend.baseUrl'); + const title = configApi.getString('app.title'); // ... } }; diff --git a/docs/frontend-system/utility-apis/04-configuring.md b/docs/frontend-system/utility-apis/04-configuring.md index d6b6167ca2..334fb4d6b5 100644 --- a/docs/frontend-system/utility-apis/04-configuring.md +++ b/docs/frontend-system/utility-apis/04-configuring.md @@ -33,8 +33,8 @@ interface WorkApiConfig { /* highlight-add-end */ const workApi = createApiExtension({ - api: workApiRef, /* highlight-add-start */ + api: workApiRef, configSchema: createSchemaFromZod(z => z.object({ goSlow: z.boolean().default(false), @@ -42,24 +42,23 @@ const workApi = createApiExtension({ ), /* highlight-add-end */ /* highlight-remove-next-line */ - factory: () => + factory: createApiFactory({ /* highlight-add-next-line */ - factory: ({ config }) => - createApiFactory({ - api: workApiRef, - deps: { storageApi: storageApiRef }, - factory: ({ storageApi }) => { - /* highlight-add-start */ - if (config.goSlow) { - /* ... */ - } - /* highlight-add-end */ - }, - }), + factory: ({ config }) => createApiFactory({ + api: workApiRef, + deps: { storageApi: storageApiRef }, + factory: ({ storageApi }) => { + /* highlight-add-start */ + if (config.goSlow) { + /* ... */ + } + /* highlight-add-end */ + }, + }), }); ``` -We wanted users to be able to configure a `goSlow` parameter for our API instances. So we added another interface type for holding our various options, and passed in a `configSchema` to `createApiExtension` which matches that interface. This example builds it using [the zod library](https://zod.dev/). The actual config values will then be passed in to the `factory` callback, where we can do what we wish with them. +We wanted users to be able to configure a `goSlow` parameter for our API instances. So we added another interface type for holding our various options, and passed in a `configSchema` to `createApiExtension` which matches that interface. This example builds it using [the zod library](https://zod.dev/). The actual config values will then be passed in to the `factory` which is now a callback, wherein we can do what we wish with them. When changing to the callback form, we also had to add a top level `api: workApiRef` under `createApiExtension`. Note that while we use the word "config" here, it's _not_ the same thing as the `configApi` which gives you access to the full app-config. The config discussed here is instead the particular configuration settings given to your utility API instance. This is discussed more [in the section below](#configuring). diff --git a/docs/frontend-system/utility-apis/05-migrating.md b/docs/frontend-system/utility-apis/05-migrating.md index b4b456e65f..b8cb50c224 100644 --- a/docs/frontend-system/utility-apis/05-migrating.md +++ b/docs/frontend-system/utility-apis/05-migrating.md @@ -12,8 +12,7 @@ If you are migrating your plugins or app over from the old frontend system, ther - Migrate your repo overall to the latest release of Backstage - Follow the plugin migration guide -- Change your package dependencies from `core-*-api` to `frontend-*-api` -- Change the imports in your code from `core-*-api` to `frontend-*-api` +- Optionally change your package dependencies and code from `core-*-api` to `frontend-*-api` - Keep the TypeScript interface and API ref exported as they were, except possibly reconsidering the choice of ID of the latter - Wrap the old API factory call in an extension using `createApiExtension` - Make sure that this extension is referenced by your migrated plugin @@ -24,26 +23,14 @@ This guide assumes that you first [upgrade your repo](../../getting-started/keep ## Dependency changes -In this article we will discuss some interfaces that you used to import from the `@backstage/core-plugin-api` package. Those are now generally moved over to `@backstage/frontend-plugin-api`, so you will want to update both your `package.json` and your source code. This applies both in your `-react` package and your main plugin package. +In this article we will discuss some old interfaces that you used to import from the `@backstage/core-plugin-api` package. Those are now generally lifted over to `@backstage/frontend-plugin-api`, next to the new interfaces that are specific to the new frontend system. If you want to, you can already update your `package.json` and code imports to only use the new plugin API, but for the time being you don't have to. The old core exports will continue to work for the foreseeable future. -First `package.json`. The following commands are examples - note that they refer to `plugins/example`, which you'll have to update to the actual folder name that your package to migrate is in. +To at least get access to the new interfaces, you'll need to run the following command. Note that it's just an example! It refers to `plugins/example`, which you'll have to change to the actual folder name that your package to migrate is in. ```bash title="from your repo root" -yarn --cwd plugins/example remove @backstage/core-plugin-api ; yarn --cwd plugins/example add @backstage/frontend-plugin-api ``` -Now in all of the code files in that package: - -```tsx title="in your source code" -/* highlight-remove-next-line */ -import { createApiRef } from '@backstage/core-plugin-api'; -/* highlight-add-next-line */ -import { createApiRef } from '@backstage/frontend-plugin-api'; -``` - -These can typically be search-and-replaced wholesale - the interfaces in the new package are mostly identical to the old one. The `createApiRef` is just an example, and the same replacement makes sense for all of the other symbols from the core package as well. - ## React package interface and ref changes Let's begin with [your `-react` package](../../architecture-decisions/adr011-plugin-package-structure.md). The act of exporting TypeScript interfaces and API refs have not changed from the old system. You can typically keep those as-is. For illustrative purposes, this is an example of an interface and its API ref: @@ -100,7 +87,7 @@ export const catalogPlugin = createPlugin({ The major changes we'll make are -- Change the import to the new package as per the top section of this guide +- Optionally change the old imports to the new package as per the top section of this guide - Wrap the existing API factory in a `createApiExtension` - Change to the new version of `createPlugin` which exports this extension - Change the plugin export to be the default instead @@ -116,14 +103,11 @@ import { workApiRef } from '@internal/plugin-example-react'; import { WorkImpl } from './WorkImpl'; const workApi = createApiExtension({ - api: workApiRef, - factory: () => - // The factory itself is unchanged - createApiFactory({ - api: workApiRef, - deps: { storageApi: storageApiRef }, - factory: ({ storageApi }) => new WorkImpl({ storageApi }), - }), + factory: createApiFactory({ + api: workApiRef, + deps: { storageApi: storageApiRef }, + factory: ({ storageApi }) => new WorkImpl({ storageApi }), + }), }); /** @public */