@backstage/core-plugin-api 1.12.4-next.0 → 1.12.4

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @backstage/core-plugin-api
 
+## 1.12.4
+
+### Patch Changes
+
+- d911b72: Updated `createApiRef` to preserve the direct config call without deprecation warnings while staying compatible with the new frontend API ref typing.
+- 59752a2: Deprecated `AlertApi`, `AlertMessage`, and `alertApiRef` in favor of the new `ToastApi` from `@backstage/frontend-plugin-api`.
+- 0452d02: Add optional `description` field to plugin-level feature flags.
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+- fe848e0: Changed `useApiHolder` to return an empty `ApiHolder` instead of throwing when used outside of an API context.
+- Updated dependencies
+  - @backstage/frontend-plugin-api@0.15.0
+
+## 1.12.4-next.1
+
+### Patch Changes
+
+- 0452d02: Add optional `description` field to plugin-level feature flags.
+- fe848e0: Changed `useApiHolder` to return an empty `ApiHolder` instead of throwing when used outside of an API context.
+- Updated dependencies
+  - @backstage/frontend-plugin-api@0.15.0-next.1
+
 ## 1.12.4-next.0
 
 ### Patch Changes

package/dist/apis/definitions/AnalyticsApi.esm.js

@@ -1,4 +1,5 @@
-import { createApiRef } from '@backstage/frontend-plugin-api';
+import '@backstage/frontend-plugin-api';
+import { createApiRef } from '../system/ApiRef.esm.js';
 
 const analyticsApiRef = createApiRef({
   id: "core.analytics"

package/dist/apis/definitions/AnalyticsApi.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsApi.esm.js","sources":["../../../src/apis/definitions/AnalyticsApi.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { ApiRef, createApiRef } from '../system';\nimport { AnalyticsContextValue } from '../../analytics/types';\n\n/**\n * Represents an event worth tracking in an analytics system that could inform\n * how users of a Backstage instance are using its features.\n *\n * @public\n */\nexport type AnalyticsEvent = {\n  /**\n   * A string that identifies the event being tracked by the type of action the\n   * event represents. Be careful not to encode extra metadata in this string\n   * that should instead be placed in the Analytics Context or attributes.\n   * Examples include:\n   *\n   * - view\n   * - click\n   * - filter\n   * - search\n   * - hover\n   * - scroll\n   */\n  action: string;\n\n  /**\n   * A string that uniquely identifies the object that the action is being\n   * taken on. Examples include:\n   *\n   * - The path of the page viewed\n   * - The url of the link clicked\n   * - The value that was filtered by\n   * - The text that was searched for\n   */\n  subject: string;\n\n  /**\n   * An optional numeric value relevant to the event that could be aggregated\n   * by analytics tools. Examples include:\n   *\n   * - The index or position of the clicked element in an ordered list\n   * - The percentage of an element that has been scrolled through\n   * - The amount of time that has elapsed since a fixed point\n   * - A satisfaction score on a fixed scale\n   */\n  value?: number;\n\n  /**\n   * Optional, additional attributes (representing dimensions or metrics)\n   * specific to the event that could be forwarded on to analytics systems.\n   */\n  attributes?: AnalyticsEventAttributes;\n\n  /**\n   * Contextual metadata relating to where the event was captured and by whom.\n   * This could include information about the route, plugin, or extension in\n   * which an event was captured.\n   */\n  context: AnalyticsContextValue;\n};\n\n/**\n * A structure allowing other arbitrary metadata to be provided by analytics\n * event emitters.\n *\n * @public\n */\nexport type AnalyticsEventAttributes = {\n  [attribute in string]: string | boolean | number;\n};\n\n/**\n * Represents a tracker with methods that can be called to track events in a\n * configured analytics service.\n *\n * @public\n */\nexport type AnalyticsTracker = {\n  captureEvent: (\n    action: string,\n    subject: string,\n    options?: {\n      value?: number;\n      attributes?: AnalyticsEventAttributes;\n    },\n  ) => void;\n};\n\n/**\n * The Analytics API is used to track user behavior in a Backstage instance.\n *\n * @remarks\n *\n * To instrument your App or Plugin, retrieve an analytics tracker using the\n * useAnalytics() hook. This will return a pre-configured AnalyticsTracker\n * with relevant methods for instrumentation.\n *\n * @public\n */\nexport type AnalyticsApi = {\n  /**\n   * Primary event handler responsible for compiling and forwarding events to\n   * an analytics system.\n   */\n  captureEvent(event: AnalyticsEvent): void;\n};\n\n/**\n * The `ApiRef` of {@link AnalyticsApi}.\n *\n * @public\n */\nexport const analyticsApiRef: ApiRef<AnalyticsApi> = createApiRef({\n  id: 'core.analytics',\n});\n"],"names":[],"mappings":";;AAgIO,MAAM,kBAAwC,YAAA,CAAa;AAAA,EAChE,EAAA,EAAI;AACN,CAAC;;;;"}
+{"version":3,"file":"AnalyticsApi.esm.js","sources":["../../../src/apis/definitions/AnalyticsApi.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { ApiRef, createApiRef } from '../system';\nimport { AnalyticsContextValue } from '../../analytics/types';\n\n/**\n * Represents an event worth tracking in an analytics system that could inform\n * how users of a Backstage instance are using its features.\n *\n * @public\n */\nexport type AnalyticsEvent = {\n  /**\n   * A string that identifies the event being tracked by the type of action the\n   * event represents. Be careful not to encode extra metadata in this string\n   * that should instead be placed in the Analytics Context or attributes.\n   * Examples include:\n   *\n   * - view\n   * - click\n   * - filter\n   * - search\n   * - hover\n   * - scroll\n   */\n  action: string;\n\n  /**\n   * A string that uniquely identifies the object that the action is being\n   * taken on. Examples include:\n   *\n   * - The path of the page viewed\n   * - The url of the link clicked\n   * - The value that was filtered by\n   * - The text that was searched for\n   */\n  subject: string;\n\n  /**\n   * An optional numeric value relevant to the event that could be aggregated\n   * by analytics tools. Examples include:\n   *\n   * - The index or position of the clicked element in an ordered list\n   * - The percentage of an element that has been scrolled through\n   * - The amount of time that has elapsed since a fixed point\n   * - A satisfaction score on a fixed scale\n   */\n  value?: number;\n\n  /**\n   * Optional, additional attributes (representing dimensions or metrics)\n   * specific to the event that could be forwarded on to analytics systems.\n   */\n  attributes?: AnalyticsEventAttributes;\n\n  /**\n   * Contextual metadata relating to where the event was captured and by whom.\n   * This could include information about the route, plugin, or extension in\n   * which an event was captured.\n   */\n  context: AnalyticsContextValue;\n};\n\n/**\n * A structure allowing other arbitrary metadata to be provided by analytics\n * event emitters.\n *\n * @public\n */\nexport type AnalyticsEventAttributes = {\n  [attribute in string]: string | boolean | number;\n};\n\n/**\n * Represents a tracker with methods that can be called to track events in a\n * configured analytics service.\n *\n * @public\n */\nexport type AnalyticsTracker = {\n  captureEvent: (\n    action: string,\n    subject: string,\n    options?: {\n      value?: number;\n      attributes?: AnalyticsEventAttributes;\n    },\n  ) => void;\n};\n\n/**\n * The Analytics API is used to track user behavior in a Backstage instance.\n *\n * @remarks\n *\n * To instrument your App or Plugin, retrieve an analytics tracker using the\n * useAnalytics() hook. This will return a pre-configured AnalyticsTracker\n * with relevant methods for instrumentation.\n *\n * @public\n */\nexport type AnalyticsApi = {\n  /**\n   * Primary event handler responsible for compiling and forwarding events to\n   * an analytics system.\n   */\n  captureEvent(event: AnalyticsEvent): void;\n};\n\n/**\n * The `ApiRef` of {@link AnalyticsApi}.\n *\n * @public\n */\nexport const analyticsApiRef: ApiRef<AnalyticsApi> = createApiRef({\n  id: 'core.analytics',\n});\n"],"names":[],"mappings":";;;AAgIO,MAAM,kBAAwC,YAAA,CAAa;AAAA,EAChE,EAAA,EAAI;AACN,CAAC;;;;"}

package/dist/apis/system/ApiRef.esm.js

@@ -0,0 +1,9 @@
+import { createApiRef as createApiRef$1 } from '@backstage/frontend-plugin-api';
+
+const createFrontendApiRefCompat = createApiRef$1;
+function createApiRef(config) {
+  return createFrontendApiRefCompat(config);
+}
+
+export { createApiRef };
+//# sourceMappingURL=ApiRef.esm.js.map

package/dist/apis/system/ApiRef.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiRef.esm.js","sources":["../../../src/apis/system/ApiRef.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  createApiRef as createFrontendApiRef,\n  type ApiRef,\n  type ApiRefConfig,\n} from '@backstage/frontend-plugin-api';\n\nconst createFrontendApiRefCompat = createFrontendApiRef as <T>(\n  config: ApiRefConfig,\n) => ApiRef<T>;\n\n/**\n * Creates a reference to an API.\n *\n * @public\n */\nexport function createApiRef<T>(config: ApiRefConfig): ApiRef<T> {\n  return createFrontendApiRefCompat<T>(config);\n}\n\nexport type { ApiRefConfig };\n"],"names":["createFrontendApiRef"],"mappings":";;AAsBA,MAAM,0BAAA,GAA6BA,cAAA;AAS5B,SAAS,aAAgB,MAAA,EAAiC;AAC/D,EAAA,OAAO,2BAA8B,MAAM,CAAA;AAC7C;;;;"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType, PropsWithChildren, ReactElement } from 'react';
-import { ApiRef, AnyApiFactory } from '@backstage/frontend-plugin-api';
-export { AlertApi, AlertMessage, AnyApiFactory, AnyApiRef, ApiFactory, ApiHolder, ApiRef, ApiRefConfig, AppTheme, AppThemeApi, AuthProviderInfo, AuthRequestOptions, BackstageIdentityApi, BackstageIdentityResponse, BackstageUserIdentity, ConfigApi, DiscoveryApi, ErrorApi, ErrorApiError, ErrorApiErrorContext, FeatureFlag, FeatureFlagState, FeatureFlagsApi, FeatureFlagsSaveOptions, FetchApi, IconComponent, IdentityApi, OAuthApi, OAuthRequestApi, OAuthRequester, OAuthRequesterOptions, OAuthScope, OpenIdConnectApi, PendingOAuthRequest, ProfileInfo, ProfileInfoApi, SessionApi, SessionState, StorageApi, StorageValueSnapshot, TypesToApiRefs, alertApiRef, appThemeApiRef, atlassianAuthApiRef, bitbucketAuthApiRef, bitbucketServerAuthApiRef, configApiRef, createApiFactory, createApiRef, discoveryApiRef, errorApiRef, featureFlagsApiRef, fetchApiRef, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, identityApiRef, microsoftAuthApiRef, oauthRequestApiRef, oktaAuthApiRef, oneloginAuthApiRef, openshiftAuthApiRef, storageApiRef, useApi, useApiHolder, vmwareCloudAuthApiRef, withApis } from '@backstage/frontend-plugin-api';
+import { ApiRefConfig, ApiRef, AnyApiFactory } from '@backstage/frontend-plugin-api';
+export { AlertApi, AlertMessage, AnyApiFactory, AnyApiRef, ApiFactory, ApiHolder, ApiRef, ApiRefConfig, AppTheme, AppThemeApi, AuthProviderInfo, AuthRequestOptions, BackstageIdentityApi, BackstageIdentityResponse, BackstageUserIdentity, ConfigApi, DiscoveryApi, ErrorApi, ErrorApiError, ErrorApiErrorContext, FeatureFlag, FeatureFlagState, FeatureFlagsApi, FeatureFlagsSaveOptions, FetchApi, IconComponent, IdentityApi, OAuthApi, OAuthRequestApi, OAuthRequester, OAuthRequesterOptions, OAuthScope, OpenIdConnectApi, PendingOAuthRequest, ProfileInfo, ProfileInfoApi, SessionApi, SessionState, StorageApi, StorageValueSnapshot, TypesToApiRefs, alertApiRef, appThemeApiRef, atlassianAuthApiRef, bitbucketAuthApiRef, bitbucketServerAuthApiRef, configApiRef, createApiFactory, discoveryApiRef, errorApiRef, featureFlagsApiRef, fetchApiRef, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, identityApiRef, microsoftAuthApiRef, oauthRequestApiRef, oktaAuthApiRef, oneloginAuthApiRef, openshiftAuthApiRef, storageApiRef, useApi, useApiHolder, vmwareCloudAuthApiRef, withApis } from '@backstage/frontend-plugin-api';
 import { BackstagePlugin as BackstagePlugin$1, IconComponent, IdentityApi } from '@backstage/core-plugin-api';
 
 /**
@@ -48,6 +48,13 @@ declare const AnalyticsContext: (options: {
     children: ReactNode;
 }) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Creates a reference to an API.
+ *
+ * @public
+ */
+declare function createApiRef<T>(config: ApiRefConfig): ApiRef<T>;
+
 /**
  * Represents an event worth tracking in an analytics system that could inform
  * how users of a Backstage instance are using its features.
@@ -562,6 +569,8 @@ type BackstagePlugin<Routes extends AnyRoutes = {}, ExternalRoutes extends AnyEx
 type PluginFeatureFlagConfig = {
     /** Feature flag name */
     name: string;
+    /** Feature flag description */
+    description?: string;
 };
 /**
  * Plugin descriptor type.
@@ -775,5 +784,5 @@ interface ElementCollection {
  */
 declare function useElementFilter<T>(node: ReactNode, filterFn: (arg: ElementCollection) => T, dependencies?: any[]): T;
 
-export { AnalyticsContext, analyticsApiRef, attachComponentData, createComponentExtension, createExternalRouteRef, createPlugin, createReactExtension, createRoutableExtension, createRouteRef, createSubRouteRef, getComponentData, useAnalytics, useApp, useElementFilter, useRouteRef, useRouteRefParams };
+export { AnalyticsContext, analyticsApiRef, attachComponentData, createApiRef, createComponentExtension, createExternalRouteRef, createPlugin, createReactExtension, createRoutableExtension, createRouteRef, createSubRouteRef, getComponentData, useAnalytics, useApp, useElementFilter, useRouteRef, useRouteRefParams };
 export type { AnalyticsApi, AnalyticsContextValue, AnalyticsEvent, AnalyticsEventAttributes, AnalyticsTracker, AnyExternalRoutes, AnyParams, AnyRouteRefParams, AnyRoutes, AppComponents, AppContext, BackstagePlugin, BootErrorPageProps, CommonAnalyticsContext, ComponentLoader, ElementCollection, ErrorBoundaryFallbackProps, Extension, ExternalRouteRef, FeatureFlagsHooks, MakeSubRouteRef, MergeParams, OptionalParams, ParamKeys, ParamNames, ParamPart, PathParams, PluginConfig, PluginFeatureFlagConfig, RouteFunc, RouteRef, SignInPageProps, SubRouteRef };

package/dist/index.esm.js

@@ -1,6 +1,7 @@
 export { AnalyticsContext } from './analytics/AnalyticsContext.esm.js';
 export { useAnalytics } from './analytics/useAnalytics.esm.js';
-export { FeatureFlagState, SessionState, alertApiRef, appThemeApiRef, atlassianAuthApiRef, bitbucketAuthApiRef, bitbucketServerAuthApiRef, configApiRef, createApiFactory, createApiRef, discoveryApiRef, errorApiRef, featureFlagsApiRef, fetchApiRef, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, identityApiRef, microsoftAuthApiRef, oauthRequestApiRef, oktaAuthApiRef, oneloginAuthApiRef, openshiftAuthApiRef, storageApiRef, useApi, useApiHolder, vmwareCloudAuthApiRef, withApis } from '@backstage/frontend-plugin-api';
+export { FeatureFlagState, SessionState, alertApiRef, appThemeApiRef, atlassianAuthApiRef, bitbucketAuthApiRef, bitbucketServerAuthApiRef, configApiRef, createApiFactory, discoveryApiRef, errorApiRef, featureFlagsApiRef, fetchApiRef, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, identityApiRef, microsoftAuthApiRef, oauthRequestApiRef, oktaAuthApiRef, oneloginAuthApiRef, openshiftAuthApiRef, storageApiRef, useApi, useApiHolder, vmwareCloudAuthApiRef, withApis } from '@backstage/frontend-plugin-api';
+export { createApiRef } from './apis/system/ApiRef.esm.js';
 export { analyticsApiRef } from './apis/definitions/AnalyticsApi.esm.js';
 export { useApp } from './app/useApp.esm.js';
 export { attachComponentData, getComponentData } from './extensions/componentData.esm.js';

package/dist/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;"}
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/core-plugin-api",
-  "version": "1.12.4-next.0",
+  "version": "1.12.4",
   "description": "Core API used by Backstage plugins",
   "backstage": {
     "role": "web-library"
@@ -57,18 +57,18 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/config": "1.3.6",
-    "@backstage/errors": "1.2.7",
-    "@backstage/frontend-plugin-api": "0.14.2-next.0",
-    "@backstage/types": "1.2.2",
-    "@backstage/version-bridge": "1.0.12",
+    "@backstage/config": "^1.3.6",
+    "@backstage/errors": "^1.2.7",
+    "@backstage/frontend-plugin-api": "^0.15.0",
+    "@backstage/types": "^1.2.2",
+    "@backstage/version-bridge": "^1.0.12",
     "history": "^5.0.0",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76 || ^4.0.0"
   },
   "devDependencies": {
-    "@backstage/cli": "0.35.5-next.0",
-    "@backstage/core-app-api": "1.19.6-next.0",
-    "@backstage/test-utils": "1.7.16-next.0",
+    "@backstage/cli": "^0.36.0",
+    "@backstage/core-app-api": "^1.19.6",
+    "@backstage/test-utils": "^1.7.16",
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^16.0.0",