diff --git a/.changeset/move-analytics-blueprint-deprecate.md b/.changeset/move-analytics-blueprint-deprecate.md new file mode 100644 index 0000000000..c4ba61966a --- /dev/null +++ b/.changeset/move-analytics-blueprint-deprecate.md @@ -0,0 +1,5 @@ +--- +'@backstage/frontend-plugin-api': patch +--- + +Deprecated `AnalyticsImplementationBlueprint` and `AnalyticsImplementationFactory` in favor of the exports from `@backstage/plugin-app-react`. diff --git a/.changeset/move-analytics-blueprint-to-app-react.md b/.changeset/move-analytics-blueprint-to-app-react.md new file mode 100644 index 0000000000..09dc530317 --- /dev/null +++ b/.changeset/move-analytics-blueprint-to-app-react.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-app-react': patch +--- + +Added `AnalyticsImplementationBlueprint` and `AnalyticsImplementationFactory`, migrated from `@backstage/frontend-plugin-api`. diff --git a/packages/frontend-plugin-api/report.api.md b/packages/frontend-plugin-api/report.api.md index c83511fc47..31a8d8ddf6 100644 --- a/packages/frontend-plugin-api/report.api.md +++ b/packages/frontend-plugin-api/report.api.md @@ -81,7 +81,7 @@ export type AnalyticsImplementation = { captureEvent(event: AnalyticsEvent): void; }; -// @public +// @public @deprecated export const AnalyticsImplementationBlueprint: ExtensionBlueprint_2<{ kind: 'analytics'; params: ( @@ -104,7 +104,7 @@ export const AnalyticsImplementationBlueprint: ExtensionBlueprint_2<{ }; }>; -// @public (undocumented) +// @public @deprecated (undocumented) export type AnalyticsImplementationFactory< Deps extends { [name in string]: unknown; diff --git a/packages/frontend-plugin-api/src/blueprints/AnalyticsImplementationBlueprint.ts b/packages/frontend-plugin-api/src/blueprints/AnalyticsImplementationBlueprint.ts index 23b5982738..f9ffb67fff 100644 --- a/packages/frontend-plugin-api/src/blueprints/AnalyticsImplementationBlueprint.ts +++ b/packages/frontend-plugin-api/src/blueprints/AnalyticsImplementationBlueprint.ts @@ -21,7 +21,10 @@ import { createExtensionDataRef, } from '../wiring'; -/** @public */ +/** + * @public + * @deprecated Use {@link AnalyticsImplementationFactory} from `@backstage/plugin-app-react` instead. + */ export type AnalyticsImplementationFactory< Deps extends { [name in string]: unknown } = {}, > = { @@ -38,6 +41,7 @@ const factoryDataRef = * Creates analytics implementations. * * @public + * @deprecated Use {@link AnalyticsImplementationBlueprint} from `@backstage/plugin-app-react` instead. */ export const AnalyticsImplementationBlueprint = createExtensionBlueprint({ kind: 'analytics', diff --git a/plugins/app-react/report.api.md b/plugins/app-react/report.api.md index 98e977ef20..a4e63e254b 100644 --- a/plugins/app-react/report.api.md +++ b/plugins/app-react/report.api.md @@ -3,6 +3,7 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts +import { AnalyticsImplementation } from '@backstage/frontend-plugin-api'; import { AppNode } from '@backstage/frontend-plugin-api'; import { AppTheme } from '@backstage/frontend-plugin-api'; import { ComponentType } from 'react'; @@ -18,6 +19,40 @@ import { RouteRef } from '@backstage/frontend-plugin-api'; import { SwappableComponentRef } from '@backstage/frontend-plugin-api'; import { TranslationMessages } from '@backstage/frontend-plugin-api'; import { TranslationResource } from '@backstage/frontend-plugin-api'; +import { TypesToApiRefs } from '@backstage/frontend-plugin-api'; + +// @public +export const AnalyticsImplementationBlueprint: ExtensionBlueprint<{ + kind: 'analytics'; + params: ( + params: AnalyticsImplementationFactory, + ) => ExtensionBlueprintParams>; + output: ExtensionDataRef< + AnalyticsImplementationFactory<{}>, + 'core.analytics.factory', + {} + >; + inputs: {}; + config: {}; + configInput: {}; + dataRefs: { + factory: ConfigurableExtensionDataRef< + AnalyticsImplementationFactory<{}>, + 'core.analytics.factory', + {} + >; + }; +}>; + +// @public (undocumented) +export type AnalyticsImplementationFactory< + Deps extends { + [name in string]: unknown; + } = {}, +> = { + deps: TypesToApiRefs; + factory(deps: Deps): AnalyticsImplementation; +}; // @public export const AppRootWrapperBlueprint: ExtensionBlueprint<{ diff --git a/plugins/app-react/src/blueprints/AnalyticsImplementationBlueprint.test.ts b/plugins/app-react/src/blueprints/AnalyticsImplementationBlueprint.test.ts new file mode 100644 index 0000000000..06ad9b877e --- /dev/null +++ b/plugins/app-react/src/blueprints/AnalyticsImplementationBlueprint.test.ts @@ -0,0 +1,54 @@ +/* + * Copyright 2025 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 { AnalyticsImplementationBlueprint } from './AnalyticsImplementationBlueprint'; + +describe('AnalyticsBlueprint', () => { + it('should create an extension with sensible defaults', () => { + const factory = { + deps: {}, + factory: () => ({ captureEvent: () => {} }), + }; + + const extension = AnalyticsImplementationBlueprint.make({ + params: define => define(factory), + name: 'test', + }); + + expect(extension).toMatchInlineSnapshot(` + { + "$$type": "@backstage/ExtensionDefinition", + "T": undefined, + "attachTo": { + "id": "api:app/analytics", + "input": "implementations", + }, + "configSchema": undefined, + "disabled": false, + "factory": [Function], + "inputs": {}, + "kind": "analytics", + "name": "test", + "output": [ + [Function], + ], + "override": [Function], + "toString": [Function], + "version": "v2", + } + `); + }); +}); diff --git a/plugins/app-react/src/blueprints/AnalyticsImplementationBlueprint.ts b/plugins/app-react/src/blueprints/AnalyticsImplementationBlueprint.ts new file mode 100644 index 0000000000..d85c926ee0 --- /dev/null +++ b/plugins/app-react/src/blueprints/AnalyticsImplementationBlueprint.ts @@ -0,0 +1,56 @@ +/* + * Copyright 2025 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 { + AnalyticsImplementation, + TypesToApiRefs, + createExtensionBlueprint, + createExtensionBlueprintParams, + createExtensionDataRef, +} from '@backstage/frontend-plugin-api'; + +/** @public */ +export type AnalyticsImplementationFactory< + Deps extends { [name in string]: unknown } = {}, +> = { + deps: TypesToApiRefs; + factory(deps: Deps): AnalyticsImplementation; +}; + +const factoryDataRef = + createExtensionDataRef().with({ + id: 'core.analytics.factory', + }); + +/** + * Creates analytics implementations. + * + * @public + */ +export const AnalyticsImplementationBlueprint = createExtensionBlueprint({ + kind: 'analytics', + attachTo: { id: 'api:app/analytics', input: 'implementations' }, + output: [factoryDataRef], + dataRefs: { + factory: factoryDataRef, + }, + defineParams: ( + params: AnalyticsImplementationFactory, + ) => createExtensionBlueprintParams(params as AnalyticsImplementationFactory), + *factory(params) { + yield factoryDataRef(params); + }, +}); diff --git a/plugins/app-react/src/blueprints/index.ts b/plugins/app-react/src/blueprints/index.ts index 318691c8db..ad9226f2a6 100644 --- a/plugins/app-react/src/blueprints/index.ts +++ b/plugins/app-react/src/blueprints/index.ts @@ -14,6 +14,10 @@ * limitations under the License. */ +export { + AnalyticsImplementationBlueprint, + type AnalyticsImplementationFactory, +} from './AnalyticsImplementationBlueprint'; export { AppRootWrapperBlueprint } from './AppRootWrapperBlueprint'; export { IconBundleBlueprint } from './IconBundleBlueprint'; export { NavContentBlueprint } from './NavContentBlueprint';