Merge pull request #7702 from backstage/blam/route-ref-deprecation

core-plugin-api: add deprecation warnings around `routeRefs`

.changeset/fluffy-moles-deny.md

@@ -0,0 +1,42 @@
+---
+'@backstage/plugin-allure': patch
+'@backstage/plugin-api-docs': patch
+'@backstage/plugin-azure-devops': patch
+'@backstage/plugin-badges': patch
+'@backstage/plugin-bazaar': patch
+'@backstage/plugin-catalog': patch
+'@backstage/plugin-catalog-graph': patch
+'@backstage/plugin-catalog-import': patch
+'@backstage/plugin-catalog-react': patch
+'@backstage/plugin-circleci': patch
+'@backstage/plugin-cloudbuild': patch
+'@backstage/plugin-code-coverage': patch
+'@backstage/plugin-config-schema': patch
+'@backstage/plugin-cost-insights': patch
+'@backstage/plugin-explore': patch
+'@backstage/plugin-firehydrant': patch
+'@backstage/plugin-gcp-projects': patch
+'@backstage/plugin-git-release-manager': patch
+'@backstage/plugin-github-actions': patch
+'@backstage/plugin-gitops-profiles': patch
+'@backstage/plugin-home': patch
+'@backstage/plugin-ilert': patch
+'@backstage/plugin-jenkins': patch
+'@backstage/plugin-kafka': patch
+'@backstage/plugin-kubernetes': patch
+'@backstage/plugin-lighthouse': patch
+'@backstage/plugin-newrelic': patch
+'@backstage/plugin-pagerduty': patch
+'@backstage/plugin-rollbar': patch
+'@backstage/plugin-scaffolder': patch
+'@backstage/plugin-search': patch
+'@backstage/plugin-sentry': patch
+'@backstage/plugin-splunk-on-call': patch
+'@backstage/plugin-tech-radar': patch
+'@backstage/plugin-techdocs': patch
+'@backstage/plugin-todo': patch
+'@backstage/plugin-user-settings': patch
+'@backstage/plugin-xcmetrics': patch
+---
+
+Refactor out the deprecated path and icon from RouteRefs

.changeset/lucky-ads-shout.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core-plugin-api': patch
+---
+
+Add deprecation warnings around `title` `icon` and `path` as they are no longer controlled when creating `routeRefs`

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

@@ -23,7 +23,6 @@ import {
 } from './types';
 import { OldIconComponent } from '../icons/types';
 
-// TODO(Rugvip): Remove this in the next breaking release, it's exported but unused
 /**
  * @deprecated
  * @internal
@@ -49,21 +48,45 @@ export class RouteRefImpl<Params extends AnyParams>
     private readonly id: string,
     readonly params: ParamKeys<Params>,
     private readonly config: {
+      /** @deprecated */
       path?: string;
+      /** @deprecated */
       icon?: OldIconComponent;
+      /** @deprecated */
       title?: string;
     },
-  ) {}
+  ) {
+    if (config.path) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[core-plugin-api] - routeRefs no longer decide their own path, please remove the path for ${this.toString()}. This will be removed in upcoming versions.`,
+      );
+    }
+
+    if (config.icon) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[core-plugin-api] - routeRefs no longer decide their own icon, please remove the icon for ${this.toString()}. This will be removed in upcoming versions.`,
+      );
+    }
+
+    if (config.title) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[core-plugin-api] - routeRefs no longer decide their own title, please remove the title for ${this.toString()}. This will be removed in upcoming versions.`,
+      );
+    }
+  }
+
+  /** @deprecated use `useRouteRef` instead */
+  get path() {
+    return this.config.path ?? '';
+  }
 
   get icon() {
     return this.config.icon;
   }
 
-  // TODO(Rugvip): Remove this, routes are looked up via the registry instead
-  get path() {
-    return this.config.path ?? '';
-  }
-
   get title() {
     return this.config.title ?? this.id;
   }

plugins/allure/src/plugin.ts

@@ -23,7 +23,7 @@ import {
 import { AllureApiClient, allureApiRef } from './api';
 
 export const allureRouteRef = createRouteRef({
-  title: 'allure-report',
+  id: 'allure',
 });
 
 export const allurePlugin = createPlugin({

plugins/api-docs/src/routes.ts

@@ -19,12 +19,8 @@ import {
   createRouteRef,
 } from '@backstage/core-plugin-api';
 
-const NoIcon = () => null;
-
 export const rootRoute = createRouteRef({
-  icon: NoIcon,
-  path: '/api-docs',
-  title: 'APIs',
+  id: 'api-docs',
 });
 
 export const createComponentRouteRef = createExternalRouteRef({

plugins/badges/src/api/BadgesClient.ts

@@ -17,7 +17,6 @@
 import { generatePath } from 'react-router';
 import { ResponseError } from '@backstage/errors';
 import { Entity, ENTITY_DEFAULT_NAMESPACE } from '@backstage/catalog-model';
-import { entityRoute } from '@backstage/plugin-catalog-react';
 import { BadgesApi, BadgeSpec } from './types';
 import { DiscoveryApi, IdentityApi } from '@backstage/core-plugin-api';
 
@@ -53,7 +52,7 @@ export class BadgesClient implements BadgesApi {
 
   private async getEntityBadgeSpecsUrl(entity: Entity): Promise<string> {
     const routeParams = this.getEntityRouteParams(entity);
-    const path = generatePath(entityRoute.path, routeParams);
+    const path = generatePath(`:kind/:namespace/:name`, routeParams);
     return `${await this.discoveryApi.getBaseUrl(
       'badges',
     )}/entity/${path}/badge-specs`;

plugins/bazaar/src/routes.ts

@@ -17,5 +17,5 @@
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  title: 'bazaar',
+  id: 'bazaar',
 });

plugins/catalog-graph/src/routes.ts

@@ -24,8 +24,7 @@ import {
  * @public
  */
 export const catalogGraphRouteRef = createRouteRef({
-  path: '/catalog-graph',
-  title: 'Catalog Graph',
+  id: 'catalog-graph',
 });
 
 /**

plugins/catalog-import/src/plugin.ts

@@ -31,8 +31,7 @@ import { catalogApiRef } from '@backstage/plugin-catalog-react';
 import { catalogImportApiRef, CatalogImportClient } from './api';
 
 export const rootRouteRef = createRouteRef({
-  path: '',
-  title: 'catalog-import',
+  id: 'catalog-import',
 });
 
 export const catalogImportPlugin = createPlugin({

plugins/catalog-react/src/routes.ts

@@ -17,22 +17,18 @@
 import { Entity, ENTITY_DEFAULT_NAMESPACE } from '@backstage/catalog-model';
 import { createRouteRef } from '@backstage/core-plugin-api';
 
-const NoIcon = () => null;
-
 // TODO(Rugvip): Move these route refs back to the catalog plugin once we're all ported to using external routes
 export const rootRoute = createRouteRef({
-  icon: NoIcon,
-  path: '',
-  title: 'Catalog',
+  id: 'catalog',
 });
+
 export const catalogRouteRef = rootRoute;
 
 export const entityRoute = createRouteRef({
-  icon: NoIcon,
-  path: ':namespace/:kind/:name/*',
-  title: 'Entity',
+  id: 'catalog:entity',
   params: ['namespace', 'kind', 'name'],
 });
+
 export const entityRouteRef = entityRoute;
 
 // Utility function to get suitable route params for entityRoute, given an

plugins/catalog/src/components/Router.tsx

@@ -16,8 +16,6 @@
 import { ENTITY_DEFAULT_NAMESPACE } from '@backstage/catalog-model';
 import {
   AsyncEntityProvider,
-  entityRoute,
-  rootRoute,
   useEntity,
   useEntityFromUrl,
 } from '@backstage/plugin-catalog-react';
@@ -87,9 +85,9 @@ export const Router = ({
   EntityPage?: ComponentType;
 }) => (
   <Routes>
-    <Route path={`${rootRoute.path}`} element={<CatalogPage />} />
+    <Route path="/" element={<CatalogPage />} />
     <Route
-      path={`${entityRoute.path}`}
+      path="/:namespace/:kind/:name"
       element={
         <EntityLoader>
           <EntityPageSwitch EntityPage={EntityPage} />

plugins/circleci/api-report.md

@@ -16,7 +16,9 @@ import { DiscoveryApi } from '@backstage/core-plugin-api';
 import { Entity } from '@backstage/catalog-model';
 import { GitType } from 'circleci-api';
 import { Me } from 'circleci-api';
+import { PathParams } from '@backstage/core-plugin-api';
 import { RouteRef } from '@backstage/core-plugin-api';
+import { SubRouteRef } from '@backstage/core-plugin-api';
 
 export { BuildStepAction };
 
@@ -68,7 +70,7 @@ export const circleCIApiRef: ApiRef<CircleCIApi>;
 // Warning: (ae-missing-release-tag) "circleCIBuildRouteRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
-export const circleCIBuildRouteRef: RouteRef<undefined>;
+export const circleCIBuildRouteRef: SubRouteRef<PathParams<'/:buildId'>>;
 
 // Warning: (ae-missing-release-tag) "circleCIPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //

plugins/circleci/src/components/BuildsPage/lib/CITable/CITable.tsx

@@ -26,7 +26,7 @@ import {
 import RetryIcon from '@material-ui/icons/Replay';
 import GitHubIcon from '@material-ui/icons/GitHub';
 import LaunchIcon from '@material-ui/icons/Launch';
-import { Link as RouterLink, generatePath } from 'react-router-dom';
+import { Link as RouterLink } from 'react-router-dom';
 import { durationHumanized, relativeTimeTo } from '../../../../util';
 import { circleCIBuildRouteRef } from '../../../../route-refs';
 import {
@@ -38,6 +38,7 @@ import {
   Table,
   TableColumn,
 } from '@backstage/core-components';
+import { useRouteRef } from '@backstage/core-plugin-api';
 
 export type CITableBuildInfo = {
   id: string;
@@ -144,16 +145,21 @@ const generatedColumns: TableColumn[] = [
     field: 'buildName',
     highlight: true,
     width: '20%',
-    render: (row: Partial<CITableBuildInfo>) => (
-      <Link
-        component={RouterLink}
-        to={`${generatePath(circleCIBuildRouteRef.path, {
-          buildId: row.id!,
-        })}`}
-      >
-        {row.buildName ? row.buildName : row?.workflow?.name}
-      </Link>
-    ),
+    render: (row: Partial<CITableBuildInfo>) => {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      const routeLink = useRouteRef(circleCIBuildRouteRef);
+
+      return (
+        <Link
+          component={RouterLink}
+          to={`${routeLink({
+            buildId: row.id!,
+          })}`}
+        >
+          {row.buildName ? row.buildName : row?.workflow?.name}
+        </Link>
+      );
+    },
   },
   {
     title: 'Job',

plugins/circleci/src/components/Router.tsx

@@ -16,7 +16,7 @@
 
 import React from 'react';
 import { Routes, Route } from 'react-router';
-import { circleCIRouteRef, circleCIBuildRouteRef } from '../route-refs';
+import { circleCIBuildRouteRef } from '../route-refs';
 import { BuildWithStepsPage } from './BuildWithStepsPage/';
 import { BuildsPage } from './BuildsPage';
 import { CIRCLECI_ANNOTATION } from '../constants';
@@ -41,9 +41,9 @@ export const Router = (_props: Props) => {
 
   return (
     <Routes>
-      <Route path={`/${circleCIRouteRef.path}`} element={<BuildsPage />} />
+      <Route path="/" element={<BuildsPage />} />
       <Route
-        path={`/${circleCIBuildRouteRef.path}`}
+        path={`${circleCIBuildRouteRef.path}`}
         element={<BuildWithStepsPage />}
       />
     </Routes>

plugins/circleci/src/route-refs.tsx

@@ -14,30 +14,14 @@
  * limitations under the License.
  */
 
-import React from 'react';
-import { SvgIcon, SvgIconProps } from '@material-ui/core';
-import { createRouteRef } from '@backstage/core-plugin-api';
-
-const CircleCIIcon = (props: SvgIconProps) => (
-  <SvgIcon
-    {...props}
-    enableBackground="new 0 0 200 200"
-    viewBox="0 0 103.8 105.2"
-  >
-    <path
-      d="m38.6 52.6c0-6.9 5.6-12.5 12.5-12.5s12.5 5.6 12.5 12.5-5.6 12.5-12.5 12.5c-6.9.1-12.5-5.6-12.5-12.5zm12.5-52.6c-24.6 0-45.2 16.8-51 39.6 0 .2-.1.3-.1.5 0 1.4 1.1 2.5 2.5 2.5h21.2c1 0 1.9-.6 2.3-1.5 4.4-9.5 13.9-16.1 25.1-16.1 15.2 0 27.6 12.4 27.6 27.6s-12.4 27.6-27.6 27.6c-11.1 0-20.7-6.6-25.1-16.1-.4-.9-1.3-1.5-2.3-1.5h-21.2c-1.4 0-2.5 1.1-2.5 2.5 0 .2 0 .3.1.5 5.8 22.8 26.4 39.6 51 39.6 29.1 0 52.7-23.6 52.7-52.7 0-29-23.6-52.5-52.7-52.5z"
-      fill="#343434"
-    />
-  </SvgIcon>
-);
+import { createRouteRef, createSubRouteRef } from '@backstage/core-plugin-api';
 
 export const circleCIRouteRef = createRouteRef({
-  icon: CircleCIIcon,
-  path: '',
-  title: 'CircleCI | All builds',
+  id: 'circle-ci',
 });
 
-export const circleCIBuildRouteRef = createRouteRef({
-  path: ':buildId',
-  title: 'CircleCI | Build info',
+export const circleCIBuildRouteRef = createSubRouteRef({
+  id: 'circle-ci/build',
+  parent: circleCIRouteRef,
+  path: '/:buildId',
 });

plugins/cloudbuild/src/components/Router.tsx

@@ -17,7 +17,7 @@ import React from 'react';
 import { Entity } from '@backstage/catalog-model';
 import { useEntity } from '@backstage/plugin-catalog-react';
 import { Routes, Route } from 'react-router';
-import { rootRouteRef, buildRouteRef } from '../routes';
+import { buildRouteRef } from '../routes';
 import { WorkflowRunDetails } from './WorkflowRunDetails';
 import { WorkflowRunsTable } from './WorkflowRunsTable';
 import { CLOUDBUILD_ANNOTATION } from './useProjectName';
@@ -40,15 +40,11 @@ export const Router = (_props: Props) => {
   }
   return (
     <Routes>
+      <Route path="/" element={<WorkflowRunsTable entity={entity} />} />
       <Route
-        path={`/${rootRouteRef.path}`}
-        element={<WorkflowRunsTable entity={entity} />}
-      />
-      <Route
-        path={`/${buildRouteRef.path}`}
+        path={`${buildRouteRef.path}`}
         element={<WorkflowRunDetails entity={entity} />}
       />
-      )
     </Routes>
   );
 };

plugins/cloudbuild/src/components/WorkflowRunsTable/WorkflowRunsTable.test.tsx

@@ -18,6 +18,7 @@ import { renderInTestApp } from '@backstage/test-utils';
 import React from 'react';
 import { WorkflowRunsTableView } from './WorkflowRunsTable';
 import { WorkflowRun } from '../useWorkflowRuns';
+import { rootRouteRef } from '../../routes';
 
 describe('<WorkflowRunsTableView />', () => {
   let runs: WorkflowRun[] = [];
@@ -56,6 +57,7 @@ describe('<WorkflowRunsTableView />', () => {
         runs={runs}
         total={runs.length}
       />,
+      { mountedRoutes: { '/': rootRouteRef } },
     );
 
     expect(getByTestId('cell-source')).toHaveAttribute('href', '/run_id_1');
@@ -74,6 +76,7 @@ describe('<WorkflowRunsTableView />', () => {
         runs={runs}
         total={runs.length}
       />,
+      { mountedRoutes: { '/': rootRouteRef } },
     );
 
     expect(getByTestId('cell-created')).toHaveTextContent(
@@ -94,6 +97,7 @@ describe('<WorkflowRunsTableView />', () => {
         runs={runs}
         total={runs.length}
       />,
+      { mountedRoutes: { '/': rootRouteRef } },
     );
 
     const rerunActionElement = getByTestId('action-rerun');

plugins/cloudbuild/src/components/WorkflowRunsTable/WorkflowRunsTable.tsx

@@ -17,7 +17,7 @@ import React from 'react';
 import { Link, Typography, Box, IconButton, Tooltip } from '@material-ui/core';
 import RetryIcon from '@material-ui/icons/Replay';
 import GoogleIcon from '@material-ui/icons/CloudCircle';
-import { Link as RouterLink, generatePath } from 'react-router-dom';
+import { Link as RouterLink } from 'react-router-dom';
 import { useWorkflowRuns, WorkflowRun } from '../useWorkflowRuns';
 import { WorkflowRunStatus } from '../WorkflowRunStatus';
 import SyncIcon from '@material-ui/icons/Sync';
@@ -26,6 +26,7 @@ import { Entity } from '@backstage/catalog-model';
 import { buildRouteRef } from '../../routes';
 import { DateTime } from 'luxon';
 import { Table, TableColumn } from '@backstage/core-components';
+import { useRouteRef } from '@backstage/core-plugin-api';
 
 const generatedColumns: TableColumn[] = [
   {
@@ -54,15 +55,19 @@ const generatedColumns: TableColumn[] = [
     field: 'source',
     highlight: true,
     width: '200px',
-    render: (row: Partial<WorkflowRun>) => (
-      <Link
-        component={RouterLink}
-        data-testid="cell-source"
-        to={generatePath(buildRouteRef.path, { id: row.id! })}
-      >
-        {row.message}
-      </Link>
-    ),
+    render: (row: Partial<WorkflowRun>) => {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      const routeLink = useRouteRef(buildRouteRef);
+      return (
+        <Link
+          component={RouterLink}
+          data-testid="cell-source"
+          to={routeLink({ id: row.id! })}
+        >
+          {row.message}
+        </Link>
+      );
+    },
   },
   {
     title: 'Ref',

plugins/cloudbuild/src/routes.ts

@@ -13,14 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createRouteRef } from '@backstage/core-plugin-api';
+import { createRouteRef, createSubRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '',
-  title: 'Google Cloudbuild',
+  id: 'cloudbuild',
 });
 
-export const buildRouteRef = createRouteRef({
-  path: ':id',
-  title: 'Cloudbuild Run',
+export const buildRouteRef = createSubRouteRef({
+  id: 'cloudbuild/run',
+  path: '/:id',
+  parent: rootRouteRef,
 });

plugins/code-coverage/src/routes.ts

@@ -16,5 +16,5 @@
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  title: 'code-coverage',
+  id: 'code-coverage',
 });

plugins/config-schema/src/routes.ts

@@ -16,5 +16,5 @@
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  title: 'config-schema',
+  id: 'config-schema',
 });

plugins/cost-insights/src/plugin.ts

@@ -21,18 +21,15 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '/cost-insights',
-  title: 'Cost Insights',
+  id: 'cost-insights',
 });
 
 export const projectGrowthAlertRef = createRouteRef({
-  path: '/cost-insights/investigating-growth',
-  title: 'Investigating Growth',
+  id: 'cost-insights:investigating-growth',
 });
 
 export const unlabeledDataflowAlertRef = createRouteRef({
-  path: '/cost-insights/labeling-jobs',
-  title: 'Labeling Dataflow Jobs',
+  id: 'cost-insights:labeling-jobs',
 });
 
 export const costInsightsPlugin = createPlugin({

plugins/explore/src/routes.ts

@@ -19,11 +19,8 @@ import {
   createRouteRef,
 } from '@backstage/core-plugin-api';
 
-const NoIcon = () => null;
-
 export const exploreRouteRef = createRouteRef({
-  icon: NoIcon,
-  title: 'Explore',
+  id: 'explore',
 });
 
 export const catalogEntityRouteRef = createExternalRouteRef({

plugins/firehydrant/src/routes.ts

@@ -16,5 +16,5 @@
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  title: 'firehydrant',
+  id: 'firehydrant',
 });

plugins/gcp-projects/src/routes.ts

@@ -17,14 +17,11 @@
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '/gcp-projects',
-  title: 'GCP Projects',
+  id: 'gcp-projects',
 });
 export const projectRouteRef = createRouteRef({
-  path: '/gcp-projects/project',
-  title: 'GCP Project Page',
+  id: 'gcp-projects:project',
 });
 export const newProjectRouteRef = createRouteRef({
-  path: '/gcp-projects/new',
-  title: 'GCP Project Page',
+  id: 'gcp-projects:new',
 });

plugins/git-release-manager/src/routes.ts

@@ -17,5 +17,5 @@
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  title: 'git-release-manager',
+  id: 'git-release-manager',
 });

plugins/github-actions/src/components/Router.tsx

@@ -17,7 +17,7 @@ import React from 'react';
 import { Entity } from '@backstage/catalog-model';
 import { useEntity } from '@backstage/plugin-catalog-react';
 import { Routes, Route } from 'react-router';
-import { rootRouteRef, buildRouteRef } from '../routes';
+import { buildRouteRef } from '../routes';
 import { WorkflowRunDetails } from './WorkflowRunDetails';
 import { WorkflowRunsTable } from './WorkflowRunsTable';
 import { GITHUB_ACTIONS_ANNOTATION } from './useProjectName';
@@ -41,12 +41,9 @@ export const Router = (_props: Props) => {
   }
   return (
     <Routes>
+      <Route path="/" element={<WorkflowRunsTable entity={entity} />} />
       <Route
-        path={`/${rootRouteRef.path}`}
-        element={<WorkflowRunsTable entity={entity} />}
-      />
-      <Route
-        path={`/${buildRouteRef.path}`}
+        path={`${buildRouteRef.path}`}
         element={<WorkflowRunDetails entity={entity} />}
       />
       )

plugins/github-actions/src/components/WorkflowRunsTable/WorkflowRunsTable.tsx

@@ -24,7 +24,7 @@ import {
 } from '@material-ui/core';
 import RetryIcon from '@material-ui/icons/Replay';
 import GitHubIcon from '@material-ui/icons/GitHub';
-import { Link as RouterLink, generatePath } from 'react-router-dom';
+import { Link as RouterLink } from 'react-router-dom';
 import { useWorkflowRuns, WorkflowRun } from '../useWorkflowRuns';
 import { WorkflowRunStatus } from '../WorkflowRunStatus';
 import SyncIcon from '@material-ui/icons/Sync';
@@ -34,7 +34,7 @@ import { Entity } from '@backstage/catalog-model';
 import { readGitHubIntegrationConfigs } from '@backstage/integration';
 
 import { EmptyState, Table, TableColumn } from '@backstage/core-components';
-import { configApiRef, useApi } from '@backstage/core-plugin-api';
+import { configApiRef, useApi, useRouteRef } from '@backstage/core-plugin-api';
 
 const generatedColumns: TableColumn[] = [
   {
@@ -47,14 +47,15 @@ const generatedColumns: TableColumn[] = [
     title: 'Message',
     field: 'message',
     highlight: true,
-    render: (row: Partial<WorkflowRun>) => (
-      <Link
-        component={RouterLink}
-        to={generatePath(buildRouteRef.path, { id: row.id! })}
-      >
-        {row.message}
-      </Link>
-    ),
+    render: (row: Partial<WorkflowRun>) => {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      const routeLink = useRouteRef(buildRouteRef);
+      return (
+        <Link component={RouterLink} to={routeLink({ id: row.id! })}>
+          {row.message}
+        </Link>
+      );
+    },
   },
   {
     title: 'Source',

plugins/github-actions/src/routes.ts

@@ -14,15 +14,14 @@
  * limitations under the License.
  */
 
-import { createRouteRef } from '@backstage/core-plugin-api';
+import { createRouteRef, createSubRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '',
-  title: 'GitHub Actions',
+  id: 'github-actions',
 });
 
-export const buildRouteRef = createRouteRef({
-  path: ':id',
-  params: ['id'],
-  title: 'GitHub Actions Workflow Run',
+export const buildRouteRef = createSubRouteRef({
+  id: 'github-actions/build',
+  path: '/:id',
+  parent: rootRouteRef,
 });

plugins/gitops-profiles/src/routes.ts

@@ -16,23 +16,15 @@
 
 import { createRouteRef } from '@backstage/core-plugin-api';
 
-const NoIcon = () => null;
-
 export const gitOpsClusterListRoute = createRouteRef({
-  icon: NoIcon,
-  path: '/gitops-clusters',
-  title: 'GitOps Clusters',
+  id: 'gitops-clusters',
 });
 
 export const gitOpsClusterDetailsRoute = createRouteRef({
-  icon: NoIcon,
-  path: '/gitops-cluster/:owner/:repo',
-  title: 'GitOps Cluster details',
+  id: 'gitops-cluster:details',
   params: ['owner', 'repo'],
 });
 
 export const gitOpsClusterCreateRoute = createRouteRef({
-  icon: NoIcon,
-  path: '/gitops-cluster-create',
-  title: 'GitOps Cluster create',
+  id: 'gitops-cluster:create',
 });

plugins/home/src/routes.ts

@@ -16,5 +16,5 @@
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  title: 'home',
+  id: 'home',
 });

plugins/ilert/src/route-refs.tsx

@@ -14,11 +14,8 @@
  * limitations under the License.
  */
 
-import ILertIcon from './assets/ilert.icon.svg';
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const iLertRouteRef = createRouteRef({
-  icon: ILertIcon,
-  path: '/ilert',
-  title: 'iLert',
+  id: 'ilert',
 });

plugins/jenkins/src/components/BuildsPage/lib/CITable/CITable.tsx

@@ -17,12 +17,13 @@ import React from 'react';
 import { Box, IconButton, Link, Typography, Tooltip } from '@material-ui/core';
 import RetryIcon from '@material-ui/icons/Replay';
 import JenkinsLogo from '../../../../assets/JenkinsLogo.svg';
-import { generatePath, Link as RouterLink } from 'react-router-dom';
+import { Link as RouterLink } from 'react-router-dom';
 import { JenkinsRunStatus } from '../Status';
 import { useBuilds } from '../../../useBuilds';
 import { buildRouteRef } from '../../../../plugin';
 import { Table, TableColumn } from '@backstage/core-components';
 import { Project } from '../../../../api/JenkinsApi';
+import { useRouteRef } from '@backstage/core-plugin-api';
 
 const FailCount = ({ count }: { count: number }): JSX.Element | null => {
   if (count !== 0) {
@@ -91,6 +92,8 @@ const generatedColumns: TableColumn[] = [
     field: 'fullName',
     highlight: true,
     render: (row: Partial<Project>) => {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      const routeLink = useRouteRef(buildRouteRef);
       if (!row.fullName || !row.lastBuild?.number) {
         return (
           <>
@@ -105,7 +108,7 @@ const generatedColumns: TableColumn[] = [
       return (
         <Link
           component={RouterLink}
-          to={generatePath(buildRouteRef.path, {
+          to={routeLink({
             jobFullName: encodeURIComponent(row.fullName),
             buildNumber: String(row.lastBuild?.number),
           })}

plugins/jenkins/src/components/Router.tsx

@@ -19,7 +19,7 @@ import { useEntity } from '@backstage/plugin-catalog-react';
 import React from 'react';
 import { Route, Routes } from 'react-router';
 import { JENKINS_ANNOTATION, LEGACY_JENKINS_ANNOTATION } from '../constants';
-import { buildRouteRef, rootRouteRef } from '../plugin';
+import { buildRouteRef } from '../plugin';
 import { CITable } from './BuildsPage/lib/CITable';
 import { DetailedViewPage } from './BuildWithStepsPage/';
 
@@ -41,7 +41,7 @@ export const Router = (_props: Props) => {
 
   return (
     <Routes>
-      <Route path={`/${rootRouteRef.path}`} element={<CITable />} />
+      <Route path="/" element={<CITable />} />
       <Route path={`/${buildRouteRef.path}`} element={<DetailedViewPage />} />
     </Routes>
   );

plugins/jenkins/src/plugin.ts

@@ -20,20 +20,20 @@ import {
   createPlugin,
   createRoutableExtension,
   createRouteRef,
+  createSubRouteRef,
   discoveryApiRef,
   identityApiRef,
 } from '@backstage/core-plugin-api';
 import { JenkinsClient, jenkinsApiRef } from './api';
 
 export const rootRouteRef = createRouteRef({
-  path: '',
-  title: 'Jenkins',
+  id: 'jenkins',
 });
 
-export const buildRouteRef = createRouteRef({
-  path: 'build/:jobFullName/:buildNumber',
-  params: ['jobFullName', 'buildNumber'],
-  title: 'Jenkins build',
+export const buildRouteRef = createSubRouteRef({
+  id: 'jenkins/builds',
+  path: '/builds/:jobFullName/:buildNumber',
+  parent: rootRouteRef,
 });
 
 export const jenkinsPlugin = createPlugin({

plugins/kafka/src/Router.tsx

@@ -18,7 +18,6 @@ import { Entity } from '@backstage/catalog-model';
 import React from 'react';
 import { Route, Routes } from 'react-router';
 import { useEntity } from '@backstage/plugin-catalog-react';
-import { rootCatalogKafkaRouteRef } from './plugin';
 import { KAFKA_CONSUMER_GROUP_ANNOTATION } from './constants';
 import { KafkaTopicsForConsumer } from './components/ConsumerGroupOffsets/ConsumerGroupOffsets';
 import { MissingAnnotationEmptyState } from '@backstage/core-components';
@@ -44,10 +43,7 @@ export const Router = (_props: Props) => {
 
   return (
     <Routes>
-      <Route
-        path={`${rootCatalogKafkaRouteRef.path}`}
-        element={<KafkaTopicsForConsumer />}
-      />
+      <Route path="/" element={<KafkaTopicsForConsumer />} />
     </Routes>
   );
 };

plugins/kafka/src/plugin.ts

@@ -25,8 +25,7 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const rootCatalogKafkaRouteRef = createRouteRef({
-  path: '*',
-  title: 'Kafka',
+  id: 'kafka',
 });
 
 export const kafkaPlugin = createPlugin({

plugins/kubernetes/src/Router.tsx

@@ -18,7 +18,6 @@ import React from 'react';
 import { Entity } from '@backstage/catalog-model';
 import { useEntity } from '@backstage/plugin-catalog-react';
 import { Route, Routes } from 'react-router-dom';
-import { rootCatalogKubernetesRouteRef } from './plugin';
 import { KubernetesContent } from './components/KubernetesContent';
 import { Button } from '@material-ui/core';
 import { MissingAnnotationEmptyState } from '@backstage/core-components';
@@ -53,10 +52,7 @@ export const Router = (_props: Props) => {
   ) {
     return (
       <Routes>
-        <Route
-          path={`/${rootCatalogKubernetesRouteRef.path}`}
-          element={<KubernetesContent entity={entity} />}
-        />
+        <Route path="/" element={<KubernetesContent entity={entity} />} />
       </Routes>
     );
   }

plugins/kubernetes/src/plugin.ts

@@ -28,8 +28,7 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const rootCatalogKubernetesRouteRef = createRouteRef({
-  path: '*',
-  title: 'Kubernetes',
+  id: 'kubernetes',
 });
 
 export const kubernetesPlugin = createPlugin({

plugins/lighthouse/src/plugin.ts

@@ -25,22 +25,19 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '',
-  title: 'Lighthouse',
+  id: 'lighthouse',
 });
 
 export const viewAuditRouteRef = createRouteRef({
-  path: 'audit/:id',
-  title: 'View Lighthouse Audit',
+  id: 'lighthouse:audit',
 });
 
 export const createAuditRouteRef = createRouteRef({
-  path: 'create-audit',
-  title: 'Create Lighthouse Audit',
+  id: 'lighthouse:create-audit',
 });
 
 export const entityContentRouteRef = createRouteRef({
-  title: 'Lighthouse Entity Content',
+  id: 'lighthouse:entity-content',
 });
 
 export const lighthousePlugin = createPlugin({

plugins/newrelic/src/plugin.ts

@@ -24,8 +24,7 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '/newrelic',
-  title: 'newrelic',
+  id: 'newrelic',
 });
 
 export const newRelicPlugin = createPlugin({

plugins/pagerduty/src/plugin.ts

@@ -24,8 +24,7 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '/pagerduty',
-  title: 'pagerduty',
+  id: 'pagerduty',
 });
 
 export const pagerDutyPlugin = createPlugin({

plugins/rollbar/src/components/Router.tsx

@@ -19,7 +19,6 @@ import { useEntity } from '@backstage/plugin-catalog-react';
 import React from 'react';
 import { Route, Routes } from 'react-router';
 import { ROLLBAR_ANNOTATION } from '../constants';
-import { rootRouteRef } from '../plugin';
 import { EntityPageRollbar } from './EntityPageRollbar/EntityPageRollbar';
 import { MissingAnnotationEmptyState } from '@backstage/core-components';
 
@@ -40,10 +39,7 @@ export const Router = (_props: Props) => {
 
   return (
     <Routes>
-      <Route
-        path={`/${rootRouteRef.path}`}
-        element={<EntityPageRollbar entity={entity} />}
-      />
+      <Route path="/" element={<EntityPageRollbar entity={entity} />} />
     </Routes>
   );
 };

plugins/rollbar/src/plugin.ts

@@ -26,8 +26,7 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '',
-  title: 'Rollbar',
+  id: 'rollbar',
 });
 
 export const rollbarPlugin = createPlugin({

plugins/scaffolder/src/routes.ts

@@ -24,5 +24,5 @@ export const registerComponentRouteRef = createExternalRouteRef({
 });
 
 export const rootRouteRef = createRouteRef({
-  title: 'Create new entity',
+  id: 'scaffolder',
 });

plugins/search/src/plugin.ts

@@ -26,13 +26,11 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '/search',
-  title: 'search',
+  id: 'search',
 });
 
 export const rootNextRouteRef = createRouteRef({
-  path: '/search-next',
-  title: 'search',
+  id: 'search:next',
 });
 
 export const searchPlugin = createPlugin({

plugins/sentry/src/plugin.ts

@@ -25,8 +25,7 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  path: '/sentry',
-  title: 'Sentry',
+  id: 'sentry',
 });
 
 export const sentryPlugin = createPlugin({

plugins/splunk-on-call/src/plugin.ts

@@ -24,9 +24,7 @@ import {
   createComponentExtension,
 } from '@backstage/core-plugin-api';
 
-export const rootRouteRef = createRouteRef({
-  title: 'splunk-on-call',
-});
+export const rootRouteRef = createRouteRef({ id: 'splunk-on-call' });
 
 export const splunkOnCallPlugin = createPlugin({
   id: 'splunk-on-call',

plugins/tech-radar/src/plugin.ts

@@ -25,7 +25,7 @@ import {
 } from '@backstage/core-plugin-api';
 
 const rootRouteRef = createRouteRef({
-  title: 'Tech Radar',
+  id: 'tech-radar',
 });
 
 /**

plugins/techdocs/src/routes.ts

@@ -17,17 +17,14 @@
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  id: 'techdocs-index-page',
-  title: 'TechDocs Landing Page',
+  id: 'techdocs:index-page',
 });
 
 export const rootDocsRouteRef = createRouteRef({
-  id: 'techdocs-reader-page',
-  title: 'Docs',
+  id: 'techdocs:reader-page',
   params: ['namespace', 'kind', 'name'],
 });
 
 export const rootCatalogDocsRouteRef = createRouteRef({
-  id: 'catalog-techdocs-reader-view',
-  title: 'Docs',
+  id: 'techdocs:catalog-reader-view',
 });

plugins/todo/src/routes.ts

@@ -16,5 +16,5 @@
 import { createRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  title: 'todo',
+  id: 'todo',
 });

plugins/user-settings/src/components/Settings.tsx

@@ -18,14 +18,14 @@ import React from 'react';
 import SettingsIcon from '@material-ui/icons/Settings';
 import { settingsRouteRef } from '../plugin';
 import { SidebarItem } from '@backstage/core-components';
-import { IconComponent } from '@backstage/core-plugin-api';
+import { useRouteRef, IconComponent } from '@backstage/core-plugin-api';
 
 type SettingsProps = {
   icon?: IconComponent;
 };
 
 export const Settings = (props: SettingsProps) => {
+  const routePath = useRouteRef(settingsRouteRef);
   const Icon = props.icon ? props.icon : SettingsIcon;
-
-  return <SidebarItem text="Settings" to={settingsRouteRef.path} icon={Icon} />;
+  return <SidebarItem text="Settings" to={routePath()} icon={Icon} />;
 };

plugins/user-settings/src/plugin.ts

@@ -21,8 +21,7 @@ import {
 } from '@backstage/core-plugin-api';
 
 export const settingsRouteRef = createRouteRef({
-  path: '/settings',
-  title: 'Settings',
+  id: 'user-settings',
 });
 
 export const userSettingsPlugin = createPlugin({

plugins/xcmetrics/src/components/XcmetricsLayout/XcmetricsLayout.tsx

@@ -22,24 +22,23 @@ import {
   TabbedLayout,
 } from '@backstage/core-components';
 import { Overview } from '../Overview';
-import { buildsRouteRef, rootRouteRef } from '../../routes';
-import { RouteRef, SubRouteRef } from '@backstage/core-plugin-api';
+import { buildsRouteRef } from '../../routes';
 import { BuildsPage } from '../BuildsPage';
 
 export interface TabConfig {
-  routeRef: RouteRef | SubRouteRef;
+  path: string;
   title: string;
   component: ReactChild;
 }
 
 const TABS: TabConfig[] = [
   {
-    routeRef: rootRouteRef,
+    path: '/',
     title: 'Overview',
     component: <Overview />,
   },
   {
-    routeRef: buildsRouteRef,
+    path: buildsRouteRef.path,
     title: 'Builds',
     component: <BuildsPage />,
   },
@@ -53,11 +52,7 @@ export const XcmetricsLayout = () => (
     </Header>
     <TabbedLayout>
       {TABS.map(tab => (
-        <TabbedLayout.Route
-          key={tab.routeRef.path}
-          path={tab.routeRef.path}
-          title={tab.title}
-        >
+        <TabbedLayout.Route key={tab.path} path={tab.path} title={tab.title}>
           <Content>{tab.component}</Content>
         </TabbedLayout.Route>
       ))}

plugins/xcmetrics/src/routes.ts

@@ -16,7 +16,7 @@
 import { createRouteRef, createSubRouteRef } from '@backstage/core-plugin-api';
 
 export const rootRouteRef = createRouteRef({
-  title: 'XCMetrics',
+  id: 'xcmetrics',
 });
 
 export const buildsRouteRef = createSubRouteRef({