From 2418224eb26133e1593c50108fab30f28ad9799b Mon Sep 17 00:00:00 2001 From: Camila Belo Date: Fri, 17 May 2024 15:01:07 +0200 Subject: [PATCH] refactor: apply review suggestion Signed-off-by: Camila Belo --- .changeset/many-moles-sing.md | 2 +- .../08-migrating.md | 41 +++++++++++++++++++ packages/backend-common/api-report.md | 2 +- packages/backend-common/src/config.ts | 1 + .../src/service/createServiceBuilder.ts | 2 +- plugins/app-backend/dev/index.ts | 6 +++ plugins/user-settings-backend/dev/index.ts | 30 +------------- 7 files changed, 53 insertions(+), 31 deletions(-) diff --git a/.changeset/many-moles-sing.md b/.changeset/many-moles-sing.md index e1f5203ed6..8b49f674c7 100644 --- a/.changeset/many-moles-sing.md +++ b/.changeset/many-moles-sing.md @@ -2,4 +2,4 @@ '@backstage/backend-common': patch --- -Deprecate the legacy `createServiceBuilder`. +We are deprecating the legacy `createServiceBuilder` factory, so if you are still using it, please checkout the migration guide and [migrate](https://backstage.io/docs/backend-system/building-plugins-and-modules/migrating) your plugin to use the new backend system. diff --git a/docs/backend-system/building-plugins-and-modules/08-migrating.md b/docs/backend-system/building-plugins-and-modules/08-migrating.md index 8a31251ee8..61e244de48 100644 --- a/docs/backend-system/building-plugins-and-modules/08-migrating.md +++ b/docs/backend-system/building-plugins-and-modules/08-migrating.md @@ -214,3 +214,44 @@ The above module can then be installed by the integrator alongside the kubernete backend.add(import('@backstage/plugin-kubernetes-backend')); backend.add(import('@internal/gke-cluster-supplier')); ``` + +### Dev Server + +Follow the steps below to run your migrated plugin on a local development server: + +1. First, delete the `src/run.js` and `src/service/standaloneServer.js` files in case they exist (the `backstage-cli` previously used these files to run legacy backend plugins locally, but they are no longer required). + +2. Next, create a new development backend in the `dev/index.js` file. The dev server is a lite version of a backend app that is mainly used to run your plugin locally, so a simple `kubernetes` backend local development server would look like this: + +```ts title="in dev/index.js" +// This package should be installed as a `dev` dependency +import { createBackend } from '@backstage/backend-defaults'; + +const backend = createBackend(); +// Path to the file where the plugin is export as default +backend.add(import('../src')); +backend.start(); +``` + +The development server created above will be automatically configured with the default dependency factories, but if you need to mock some of the services your plugin relies on, such as the `rootConfig` service, you can use one of the `mockServices` factories: + +```ts title="in dev/index.js" +//... +// This package should be installed as `devDependecies` +import { mockServices } from '@backstage/backend-test-utils'; + +const backend = createBackend(); +// ... +backend.add( + mockServices.rootConfig.factory({ + data: { + // your config mocked values goes here + }, + }), +); +// ... +``` + +Checkout the [custom service implementations](https://backstage.io/docs/backend-system/building-backends/index#custom-service-implementations) documentation and also the [core service configurations](https://backstage.io/docs/backend-system/core-services/index) page in case you'd like to create your own custom mock factory for one or more services. + +3. Now you can finally start your plugin locally by running `yarn start` from the root folder of your plugin. diff --git a/packages/backend-common/api-report.md b/packages/backend-common/api-report.md index 0f33539ed2..b22b50fc76 100644 --- a/packages/backend-common/api-report.md +++ b/packages/backend-common/api-report.md @@ -599,7 +599,7 @@ export type LegacyRootDatabaseService = { forPlugin(pluginId: string): PluginDatabaseManager; }; -// @public +// @public @deprecated export function loadBackendConfig(options: { logger: LoggerService; remote?: LoadConfigOptionsRemote; diff --git a/packages/backend-common/src/config.ts b/packages/backend-common/src/config.ts index b452d8db70..1dfa9643e2 100644 --- a/packages/backend-common/src/config.ts +++ b/packages/backend-common/src/config.ts @@ -29,6 +29,7 @@ import { setRootLoggerRedactionList } from './logging/createRootLogger'; * This function should only be called once, during the initialization of the backend. * * @public + * @deprecated Use {@link @backstage/backend-app-api#loadBackendConfig} instead. */ export async function loadBackendConfig(options: { logger: LoggerService; diff --git a/packages/backend-common/src/service/createServiceBuilder.ts b/packages/backend-common/src/service/createServiceBuilder.ts index 5a4f439a32..e731056f72 100644 --- a/packages/backend-common/src/service/createServiceBuilder.ts +++ b/packages/backend-common/src/service/createServiceBuilder.ts @@ -20,7 +20,7 @@ import { ServiceBuilder } from './types'; /** * Creates a new service builder. * @public - * @deprecated We are going to deprecated this old way of creating services in a near future, if you are using this service helper, please checkout the migration guide and make sure you migrate your backend to use the new system: https://backstage.io/docs/backend-system/building-backends/migrating. + * @deprecated We are going to deprecated this old way of creating services in a near future, if you are using this service helper, please checkout the {@link https://backstage.io/docs/backend-system/building-backends/migrating | backend} and {@link https://backstage.io/docs/backend-system/building-plugins-and-modules/migrating | plugin} migration guides. */ export function createServiceBuilder(_module: NodeModule): ServiceBuilder { return new ServiceBuilderImpl(_module); diff --git a/plugins/app-backend/dev/index.ts b/plugins/app-backend/dev/index.ts index 43c75d24df..03f1931337 100644 --- a/plugins/app-backend/dev/index.ts +++ b/plugins/app-backend/dev/index.ts @@ -15,7 +15,13 @@ */ import { createBackend } from '@backstage/backend-defaults'; +import { mockServices } from '@backstage/backend-test-utils'; const backend = createBackend(); +backend.add( + mockServices.rootConfig.factory({ + data: { app: { packageName: 'example-app' } }, + }), +); backend.add(import('../src/alpha')); backend.start(); diff --git a/plugins/user-settings-backend/dev/index.ts b/plugins/user-settings-backend/dev/index.ts index 31963edc95..49fa7cb6bd 100644 --- a/plugins/user-settings-backend/dev/index.ts +++ b/plugins/user-settings-backend/dev/index.ts @@ -15,35 +15,9 @@ */ import { createBackend } from '@backstage/backend-defaults'; -import { - coreServices, - createServiceFactory, -} from '@backstage/backend-plugin-api'; -import { IdentityApi } from '@backstage/plugin-auth-node'; - -const identityMock: IdentityApi = { - async getIdentity({ request }) { - const token = request.headers.authorization?.split(' ')[1]; - return { - identity: { - type: 'user', - ownershipEntityRefs: [], - userEntityRef: token || 'user:default/john_doe', - }, - token: token || 'no-token', - }; - }, -}; +import { mockServices } from '@backstage/backend-test-utils'; const backend = createBackend(); -backend.add( - createServiceFactory(() => ({ - service: coreServices.identity, - deps: {}, - async factory() { - return identityMock; - }, - })), -); +backend.add(mockServices.identity.factory()); backend.add(import('../src/alpha')); backend.start();