From 90c3a9d1c074c409268fdc7b39f449c491e43c78 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Tue, 17 Mar 2026 10:46:42 +0100
Subject: [PATCH] api-ref: preserve const ids in builder types

Use a const type parameter for createApiRef().with(...) so literal API ref ids stay narrow instead of widening to string.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
---
 packages/frontend-plugin-api/report.api.md             | 2 +-
 packages/frontend-plugin-api/src/apis/system/ApiRef.ts | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/frontend-plugin-api/report.api.md b/packages/frontend-plugin-api/report.api.md
index ae36baf2a6..e3113e1d9b 100644
--- a/packages/frontend-plugin-api/report.api.md
+++ b/packages/frontend-plugin-api/report.api.md
@@ -444,7 +444,7 @@ export function createApiRef<T>(config: ApiRefConfig): ApiRef<T> & {
 
 // @public
 export function createApiRef<T>(): {
-  with<TId extends string>(
+  with<const TId extends string>(
     config: ApiRefConfig & {
       id: TId;
       pluginId?: string;
diff --git a/packages/frontend-plugin-api/src/apis/system/ApiRef.ts b/packages/frontend-plugin-api/src/apis/system/ApiRef.ts
index 2d86f0a8ad..2327cb0631 100644
--- a/packages/frontend-plugin-api/src/apis/system/ApiRef.ts
+++ b/packages/frontend-plugin-api/src/apis/system/ApiRef.ts
@@ -119,7 +119,7 @@ export function createApiRef<T>(
  * @public
  */
 export function createApiRef<T>(): {
-  with<TId extends string>(
+  with<const TId extends string>(
     config: ApiRefConfig & { id: TId; pluginId?: string },
   ): ApiRef<T, TId> & {
     readonly $$type: '@backstage/ApiRef';
@@ -128,7 +128,7 @@ export function createApiRef<T>(): {
 export function createApiRef<T>(config?: ApiRefConfig):
   | (ApiRef<T> & { readonly $$type: '@backstage/ApiRef' })
   | {
-      with<TId extends string>(
+      with<const TId extends string>(
         config: ApiRefConfig & { id: TId; pluginId?: string },
       ): ApiRef<T, TId> & {
         readonly $$type: '@backstage/ApiRef';
@@ -139,7 +139,7 @@ export function createApiRef<T>(config?: ApiRefConfig):
     return makeApiRef<T, string>(config);
   }
   return {
-    with<TId extends string>(
+    with<const TId extends string>(
       withConfig: ApiRefConfig & { id: TId; pluginId?: string },
     ): ApiRef<T, TId> & { readonly $$type: '@backstage/ApiRef' } {
       validateId(withConfig.id);