@backstage/backend-plugin-api 1.11.0-next.1 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @backstage/backend-plugin-api
 
+## 1.11.0
+
+### Minor Changes
+
+- e956084: **BREAKING PRODUCERS**: Added an instance ID to the root instance metadata service. Custom implementations and mocks must now provide a globally unique ID that remains stable for the lifetime of the running backend instance.
+- f6054ac: Added experimental `declareConnection` and `connectionsServiceRef` exports to `@backstage/backend-plugin-api/alpha`. Plugins and modules can declare connection dependencies and request the connections service without importing private packages.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/config@1.3.10
+  - @backstage/errors@1.3.2
+  - @backstage/connections@0.4.1
+  - @backstage/plugin-auth-node@0.7.7
+  - @backstage/cli-common@0.3.2
+  - @backstage/plugin-permission-common@0.9.12
+  - @backstage/plugin-permission-node@0.11.5
+
+## 1.11.0-next.2
+
+### Minor Changes
+
+- f6054ac: Added experimental `declareConnection` and `connectionsServiceRef` exports to `@backstage/backend-plugin-api/alpha`. Plugins and modules can declare connection dependencies and request the connections service without importing private packages.
+
 ## 1.11.0-next.1
 
 ### Minor Changes

package/dist/alpha/declareConnection.cjs.js

@@ -0,0 +1,14 @@
+'use strict';
+
+function declareConnection(reg, registration) {
+  const internal = reg;
+  if (typeof internal.registerConnection !== "function") {
+    throw new Error(
+      "declareConnection: the provided registration points object does not support registerConnection. Make sure you are calling this inside a createBackendPlugin or createBackendModule register callback."
+    );
+  }
+  internal.registerConnection(registration);
+}
+
+exports.declareConnection = declareConnection;
+//# sourceMappingURL=declareConnection.cjs.js.map

package/dist/alpha/declareConnection.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declareConnection.cjs.js","sources":["../../src/alpha/declareConnection.ts"],"sourcesContent":["/*\n * Copyright 2026 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 */\nimport type {\n  BackendModuleRegistrationPoints,\n  BackendPluginRegistrationPoints,\n} from '@backstage/backend-plugin-api';\n\nimport type { ConnectionRegistration } from '../wiring/types';\n\n/**\n * Declares that a plugin or module uses a particular connection type.\n * Must be called inside the `register` callback, before `registerInit`.\n *\n * @alpha\n */\nexport function declareConnection(\n  reg: BackendPluginRegistrationPoints | BackendModuleRegistrationPoints,\n  registration: ConnectionRegistration,\n): void {\n  const internal = reg as {\n    registerConnection?: (registration: ConnectionRegistration) => void;\n  };\n  if (typeof internal.registerConnection !== 'function') {\n    throw new Error(\n      'declareConnection: the provided registration points object does not support registerConnection. ' +\n        'Make sure you are calling this inside a createBackendPlugin or createBackendModule register callback.',\n    );\n  }\n  internal.registerConnection(registration);\n}\n"],"names":[],"mappings":";;AA4BO,SAAS,iBAAA,CACd,KACA,YAAA,EACM;AACN,EAAA,MAAM,QAAA,GAAW,GAAA;AAGjB,EAAA,IAAI,OAAO,QAAA,CAAS,kBAAA,KAAuB,UAAA,EAAY;AACrD,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAEF;AAAA,EACF;AACA,EAAA,QAAA,CAAS,mBAAmB,YAAY,CAAA;AAC1C;;"}

package/dist/alpha/refs.cjs.js

@@ -2,6 +2,10 @@
 
 var backendPluginApi = require('@backstage/backend-plugin-api');
 
+const connectionsServiceRef = backendPluginApi.createServiceRef({
+  id: "alpha.core.connections",
+  scope: "plugin"
+});
 const actionsServiceRef = backendPluginApi.createServiceRef({
   id: "alpha.core.actions"
 });
@@ -17,6 +21,7 @@ const tracingServiceRef = backendPluginApi.createServiceRef({
 
 exports.actionsRegistryServiceRef = actionsRegistryServiceRef;
 exports.actionsServiceRef = actionsServiceRef;
+exports.connectionsServiceRef = connectionsServiceRef;
 exports.metricsServiceRef = metricsServiceRef;
 exports.tracingServiceRef = tracingServiceRef;
 //# sourceMappingURL=refs.cjs.js.map

package/dist/alpha/refs.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"refs.cjs.js","sources":["../../src/alpha/refs.ts"],"sourcesContent":["/*\n * Copyright 2025 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 { createServiceRef } from '@backstage/backend-plugin-api';\n\n/**\n * Service for calling distributed actions\n *\n * See {@link ActionsService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsServiceRef = createServiceRef<\n  import('./ActionsService').ActionsService\n>({\n  id: 'alpha.core.actions',\n});\n\n/**\n * Service for registering and managing distributed actions.\n *\n * See {@link ActionsRegistryService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions-registry | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsRegistryServiceRef = createServiceRef<\n  import('./ActionsRegistryService').ActionsRegistryService\n>({\n  id: 'alpha.core.actionsRegistry',\n});\n\n/**\n * Service for managing metrics.\n *\n * @alpha\n */\nexport const metricsServiceRef = createServiceRef<\n  import('./MetricsService').MetricsService\n>({\n  id: 'alpha.core.metrics',\n});\n\n/**\n * Service for managing trace spans.\n *\n * See `TracingService` for the API surface.\n *\n * @alpha\n */\nexport const tracingServiceRef = createServiceRef<\n  import('./TracingService').TracingService\n>({\n  id: 'alpha.core.tracing',\n});\n"],"names":["createServiceRef"],"mappings":";;;;AA2BO,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAWM,MAAM,4BAA4BA,iCAAA,CAEvC;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAOM,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AASM,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;;;;;"}
+{"version":3,"file":"refs.cjs.js","sources":["../../src/alpha/refs.ts"],"sourcesContent":["/*\n * Copyright 2025 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 { createServiceRef } from '@backstage/backend-plugin-api';\n\n/**\n * Service for looking up plugin-scoped connections to external systems.\n * Declare consumed connection types with `declareConnection` before requesting this service.\n *\n * @alpha\n */\nexport const connectionsServiceRef = createServiceRef<\n  import('@backstage/connections').ConnectionsService\n>({\n  id: 'alpha.core.connections',\n  scope: 'plugin',\n});\n\n/**\n * Service for calling distributed actions\n *\n * See {@link ActionsService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsServiceRef = createServiceRef<\n  import('./ActionsService').ActionsService\n>({\n  id: 'alpha.core.actions',\n});\n\n/**\n * Service for registering and managing distributed actions.\n *\n * See {@link ActionsRegistryService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions-registry | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsRegistryServiceRef = createServiceRef<\n  import('./ActionsRegistryService').ActionsRegistryService\n>({\n  id: 'alpha.core.actionsRegistry',\n});\n\n/**\n * Service for managing metrics.\n *\n * @alpha\n */\nexport const metricsServiceRef = createServiceRef<\n  import('./MetricsService').MetricsService\n>({\n  id: 'alpha.core.metrics',\n});\n\n/**\n * Service for managing trace spans.\n *\n * See `TracingService` for the API surface.\n *\n * @alpha\n */\nexport const tracingServiceRef = createServiceRef<\n  import('./TracingService').TracingService\n>({\n  id: 'alpha.core.tracing',\n});\n"],"names":["createServiceRef"],"mappings":";;;;AAwBO,MAAM,wBAAwBA,iCAAA,CAEnC;AAAA,EACA,EAAA,EAAI,wBAAA;AAAA,EACJ,KAAA,EAAO;AACT,CAAC;AAWM,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAWM,MAAM,4BAA4BA,iCAAA,CAEvC;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAOM,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AASM,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;;;;;;"}

package/dist/alpha.cjs.js

@@ -1,11 +1,14 @@
 'use strict';
 
 var refs = require('./alpha/refs.cjs.js');
+var declareConnection = require('./alpha/declareConnection.cjs.js');
 
 
 
 exports.actionsRegistryServiceRef = refs.actionsRegistryServiceRef;
 exports.actionsServiceRef = refs.actionsServiceRef;
+exports.connectionsServiceRef = refs.connectionsServiceRef;
 exports.metricsServiceRef = refs.metricsServiceRef;
 exports.tracingServiceRef = refs.tracingServiceRef;
+exports.declareConnection = declareConnection.declareConnection;
 //# sourceMappingURL=alpha.cjs.js.map

package/dist/alpha.cjs.js.map

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

package/dist/alpha.d.ts

@@ -1,11 +1,12 @@
 import { AnyZodObject, z } from 'zod/v3';
 import { BasicPermission } from '@backstage/plugin-permission-common';
 import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
-import { LoggerService, BackstageCredentials } from '@backstage/backend-plugin-api';
+import { LoggerService, BackstageCredentials, BackendPluginRegistrationPoints, BackendModuleRegistrationPoints } from '@backstage/backend-plugin-api';
 import { JsonObject, JsonValue } from '@backstage/types';
 import { JSONSchema7 } from 'json-schema';
 import { Request } from 'express';
-export { C as ConnectionRegistration } from './types/types.d-DPPAZhPl.js';
+import * as _backstage_connections from '@backstage/connections';
+import { C as ConnectionRegistration } from './types/types.d-CEuefyTb.js';
 
 /**
  * @alpha
@@ -445,6 +446,13 @@ interface TracingServiceBaggageEntry {
     value: string;
 }
 
+/**
+ * Service for looking up plugin-scoped connections to external systems.
+ * Declare consumed connection types with `declareConnection` before requesting this service.
+ *
+ * @alpha
+ */
+declare const connectionsServiceRef: _backstage_backend_plugin_api.ServiceRef<_backstage_connections.ConnectionsService, "plugin", "singleton">;
 /**
  * Service for calling distributed actions
  *
@@ -480,5 +488,13 @@ declare const metricsServiceRef: _backstage_backend_plugin_api.ServiceRef<Metric
  */
 declare const tracingServiceRef: _backstage_backend_plugin_api.ServiceRef<TracingService, "plugin", "singleton">;
 
-export { actionsRegistryServiceRef, actionsServiceRef, metricsServiceRef, tracingServiceRef };
+/**
+ * Declares that a plugin or module uses a particular connection type.
+ * Must be called inside the `register` callback, before `registerInit`.
+ *
+ * @alpha
+ */
+declare function declareConnection(reg: BackendPluginRegistrationPoints | BackendModuleRegistrationPoints, registration: ConnectionRegistration): void;
+
+export { ConnectionRegistration, actionsRegistryServiceRef, actionsServiceRef, connectionsServiceRef, declareConnection, metricsServiceRef, tracingServiceRef };
 export type { ActionsRegistryActionContext, ActionsRegistryActionExample, ActionsRegistryActionOptions, ActionsRegistryService, ActionsService, ActionsServiceAction, MetricAdvice, MetricAttributeValue, MetricAttributes, MetricOptions, MetricsService, MetricsServiceCounter, MetricsServiceGauge, MetricsServiceHistogram, MetricsServiceObservable, MetricsServiceObservableCallback, MetricsServiceObservableCounter, MetricsServiceObservableGauge, MetricsServiceObservableResult, MetricsServiceObservableUpDownCounter, MetricsServiceUpDownCounter, TracingService, TracingServiceAttributeValue, TracingServiceAttributes, TracingServiceBaggage, TracingServiceBaggageEntry, TracingServiceContext, TracingServiceContextAPI, TracingServicePropagationAPI, TracingServiceSpan, TracingServiceSpanKind, TracingServiceSpanOptions, TracingServiceSpanStatus };

package/dist/index.d.ts

@@ -6,8 +6,8 @@ import { PermissionRule, PermissionResourceRef, PermissionRuleset } from '@backs
 import { Config } from '@backstage/config';
 import { Duration } from 'luxon';
 import { Readable } from 'node:stream';
-import { S as ServiceRef, B as BackendModuleRegistrationPoints, a as BackendFeature, b as BackendPluginRegistrationPoints, E as ExtensionPoint } from './types/types.d-DPPAZhPl.js';
-export { c as ExtensionPointFactoryContext, P as PluginServiceFactoryOptions, R as RootServiceFactoryOptions, d as ServiceFactory, e as ServiceRefOptions, f as createServiceFactory, g as createServiceRef } from './types/types.d-DPPAZhPl.js';
+import { S as ServiceRef, B as BackendModuleRegistrationPoints, a as BackendFeature, b as BackendPluginRegistrationPoints, E as ExtensionPoint } from './types/types.d-CEuefyTb.js';
+export { c as ExtensionPointFactoryContext, P as PluginServiceFactoryOptions, R as RootServiceFactoryOptions, d as ServiceFactory, e as ServiceRefOptions, f as createServiceFactory, g as createServiceRef } from './types/types.d-CEuefyTb.js';
 export { isChildPath } from '@backstage/cli-common';
 
 /**

package/dist/types/{types.d-DPPAZhPl.d.ts → types.d-CEuefyTb.d.ts}

@@ -178,13 +178,13 @@ type DepsToInstances<TDeps extends {
 interface ConnectionRegistration {
     /**
      * The connection type identifier, matching the `type` field in connections
-     * config and in calls to `find` / `findOptional` on the connections service.
+     * config and in calls to `find` on the connections service.
      */
     type: string;
     /**
      * Whether the connection is essential for the plugin or module to function.
-     * If true, the backend will fail to start if no matching connection is
-     * configured. Defaults to false.
+     * Informational metadata; this does not enforce connection availability
+     * at startup. Defaults to false.
      */
     required?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "1.11.0-next.1",
+  "version": "1.11.0",
   "description": "Core API used by Backstage backend plugins",
   "backstage": {
     "role": "node-library"
@@ -65,13 +65,14 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/cli-common": "0.3.2-next.0",
-    "@backstage/config": "1.3.10-next.0",
-    "@backstage/errors": "1.3.2-next.0",
-    "@backstage/plugin-auth-node": "0.7.7-next.1",
-    "@backstage/plugin-permission-common": "0.9.12-next.0",
-    "@backstage/plugin-permission-node": "0.11.5-next.1",
-    "@backstage/types": "1.2.2",
+    "@backstage/cli-common": "^0.3.2",
+    "@backstage/config": "^1.3.10",
+    "@backstage/connections": "^0.4.1",
+    "@backstage/errors": "^1.3.2",
+    "@backstage/plugin-auth-node": "^0.7.7",
+    "@backstage/plugin-permission-common": "^0.9.12",
+    "@backstage/plugin-permission-node": "^0.11.5",
+    "@backstage/types": "^1.2.2",
     "@types/express": "^4.17.6",
     "@types/json-schema": "^7.0.6",
     "@types/luxon": "^3.0.0",
@@ -80,8 +81,8 @@
     "zod": "^3.25.76 || ^4.0.0"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "1.11.8-next.1",
-    "@backstage/cli": "0.36.7-next.0"
+    "@backstage/backend-test-utils": "^1.11.8",
+    "@backstage/cli": "^0.36.7"
   },
   "configSchema": "config.schema.json"
 }