Merge pull request #3840 from backstage/rugvip/depr

core-api: deprecate RouteRef path and remove deprecated createSubRoute

.changeset/polite-turtles-prove.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core-api': patch
+---
+
+Deprecate `RouteRef` path parameter and member, and remove deprecated `routeRef.createSubRouteRef`.

packages/core-api/src/routing/RouteRef.ts

@@ -25,25 +25,15 @@ export class AbsoluteRouteRef<Params extends { [param in string]: string }> {
 
   // TODO(Rugvip): Remove this, routes are looked up via the registry instead
   get path() {
-    return this.config.path;
+    return this.config.path ?? '';
   }
 
   get title() {
     return this.config.title;
   }
 
-  /**
-   * This function should not be used, create a separate RouteRef instead
-   * @deprecated
-   */
-  createSubRoute(): any {
-    throw new Error(
-      'This method should not be called, create a separate RouteRef instead',
-    );
-  }
-
   toString() {
-    return `routeRef{path=${this.path}}`;
+    return `routeRef{title=${this.title}}`;
   }
 }
 
@@ -54,13 +44,7 @@ export function createRouteRef<
   return new AbsoluteRouteRef<Params>(config);
 }
 
-const create = Symbol('create-external-route-ref');
-
 export class ExternalRouteRef {
-  static [create]() {
-    return new ExternalRouteRef();
-  }
-
   private constructor() {}
 
   toString() {
@@ -69,5 +53,5 @@ export class ExternalRouteRef {
 }
 
 export function createExternalRouteRef(): ExternalRouteRef {
-  return ExternalRouteRef[create]();
+  return new ((ExternalRouteRef as unknown) as { new (): ExternalRouteRef })();
 }

packages/core-api/src/routing/types.ts

@@ -19,14 +19,10 @@ import { IconComponent } from '../icons';
 // @ts-ignore, we're just embedding the Params type for usage in other places
 export type RouteRef<Params extends { [param in string]: string } = {}> = {
   // TODO(Rugvip): Remove path, look up via registry instead
+  /** @deprecated paths are no longer accessed directly from RouteRefs, use useRouteRef instead */
   path: string;
   icon?: IconComponent;
   title: string;
-  /**
-   * This function should not be used, create a separate RouteRef instead
-   * @deprecated
-   */
-  createSubRoute(): any;
 };
 
 export type AnyRouteRef = RouteRef<any>;
@@ -51,7 +47,8 @@ export type MutableRouteRef = RouteRef<{}>;
 
 export type RouteRefConfig<Params extends { [param in string]: string }> = {
   params?: Array<keyof Params>;
-  path: string;
+  /** @deprecated Route refs no longer decide their own path */
+  path?: string;
   icon?: IconComponent;
   title: string;
 };