From 49397c16e0cd9c06454a76c16d013b7450b608d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@spotify.com>
Date: Sat, 28 Mar 2026 10:58:37 +0100
Subject: [PATCH] Simplify createRouteRef type signature
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace dual TParams/TParamKeys type parameters with a single TParamKey,
removing unnecessary complexity while preserving runtime behavior.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Fredrik Adelöw <freben@spotify.com>
---
 .changeset/simplify-compat-route-ref.md       |  5 +++++
 .changeset/simplify-route-ref-types.md        |  5 +++++
 .../src/convertLegacyRouteRef.ts              |  2 +-
 packages/frontend-plugin-api/report.api.md    | 19 ++++---------------
 .../src/routing/RouteRef.ts                   | 19 ++++++-------------
 5 files changed, 21 insertions(+), 29 deletions(-)
 create mode 100644 .changeset/simplify-compat-route-ref.md
 create mode 100644 .changeset/simplify-route-ref-types.md

diff --git a/.changeset/simplify-compat-route-ref.md b/.changeset/simplify-compat-route-ref.md
new file mode 100644
index 0000000000..a9b78f8ecf
--- /dev/null
+++ b/.changeset/simplify-compat-route-ref.md
@@ -0,0 +1,5 @@
+---
+'@backstage/core-compat-api': patch
+---
+
+Removed unnecessary type argument from internal `createRouteRef` call.
diff --git a/.changeset/simplify-route-ref-types.md b/.changeset/simplify-route-ref-types.md
new file mode 100644
index 0000000000..470c2659db
--- /dev/null
+++ b/.changeset/simplify-route-ref-types.md
@@ -0,0 +1,5 @@
+---
+'@backstage/frontend-plugin-api': minor
+---
+
+Simplified the type signature of `createRouteRef` by replacing the dual `TParams`/`TParamKeys` type parameters with a single `TParamKey` parameter. This is a breaking change for callers that explicitly provided type arguments, but most usage that relies on inference is unaffected.
diff --git a/packages/core-compat-api/src/convertLegacyRouteRef.ts b/packages/core-compat-api/src/convertLegacyRouteRef.ts
index e490d83a19..c160f47789 100644
--- a/packages/core-compat-api/src/convertLegacyRouteRef.ts
+++ b/packages/core-compat-api/src/convertLegacyRouteRef.ts
@@ -220,7 +220,7 @@ function convertOldToNew(
     const legacyRef = ref as LegacyRouteRef;
     const legacyRefStr = String(legacyRef);
     const newRef = OpaqueRouteRef.toInternal(
-      createRouteRef<{ [key in string]: string }>({
+      createRouteRef({
         params: legacyRef.params as string[],
       }),
     );
diff --git a/packages/frontend-plugin-api/report.api.md b/packages/frontend-plugin-api/report.api.md
index 6ed413a66d..9752eaa6c8 100644
--- a/packages/frontend-plugin-api/report.api.md
+++ b/packages/frontend-plugin-api/report.api.md
@@ -814,25 +814,14 @@ export interface CreateFrontendPluginOptions<
 }
 
 // @public
-export function createRouteRef<
-  TParams extends
-    | {
-        [param in TParamKeys]: string;
-      }
-    | undefined = undefined,
-  TParamKeys extends string = string,
->(config?: {
-  readonly params?: string extends TParamKeys
-    ? (keyof TParams)[]
-    : TParamKeys[];
+export function createRouteRef<TParamKey extends string = never>(config?: {
+  readonly params?: TParamKey[];
   aliasFor?: string;
 }): RouteRef<
-  keyof TParams extends never
+  [TParamKey] extends [never]
     ? undefined
-    : string extends TParamKeys
-    ? TParams
     : {
-        [param in TParamKeys]: string;
+        [param in TParamKey]: string;
       }
 >;
 
diff --git a/packages/frontend-plugin-api/src/routing/RouteRef.ts b/packages/frontend-plugin-api/src/routing/RouteRef.ts
index 62f29adb86..f66c3e7d77 100644
--- a/packages/frontend-plugin-api/src/routing/RouteRef.ts
+++ b/packages/frontend-plugin-api/src/routing/RouteRef.ts
@@ -41,23 +41,16 @@ export interface RouteRef<
  * @public
  */
 export function createRouteRef<
-  // Params is the type that we care about and the one to be embedded in the route ref.
-  // For example, given the params ['name', 'kind'], Params will be {name: string, kind: string}
-  TParams extends { [param in TParamKeys]: string } | undefined = undefined,
-  TParamKeys extends string = string,
+  // ParamKey is narrowed to the literal union of param name strings.
+  // Defaulting to never means we get undefined params when the array is empty or omitted.
+  TParamKey extends string = never,
 >(config?: {
   /** A list of parameter names that the path that this route ref is bound to must contain */
-  readonly params?: string extends TParamKeys
-    ? (keyof TParams)[]
-    : TParamKeys[];
+  readonly params?: TParamKey[];
 
   aliasFor?: string;
 }): RouteRef<
-  keyof TParams extends never
-    ? undefined
-    : string extends TParamKeys
-    ? TParams
-    : { [param in TParamKeys]: string }
+  [TParamKey] extends [never] ? undefined : { [param in TParamKey]: string }
 > {
   const params = (config?.params ?? []) as string[];
   const creationSite = describeParentCallSite();
@@ -65,7 +58,7 @@ export function createRouteRef<
   let id: string | undefined = undefined;
 
   return OpaqueRouteRef.createInstance('v1', {
-    T: undefined as unknown as TParams,
+    T: undefined as any,
     getParams() {
       return params;
     },