Merge pull request #31804 from backstage/rugvip/compat-route-refs

core-plugin-api: add forwards compatibility for route refs

docs/frontend-system/building-apps/08-migrating.md

@@ -9,7 +9,7 @@ description: How to migrate existing apps to the new frontend system
 
 This section describes how to migrate an existing Backstage app package to use the new frontend system. The app package is typically found at `packages/app` in your project and is responsible for wiring together the Backstage frontend application.
 
-> **Who is this for?**  
+> **Who is this for?**
 > This guide is intended for maintainers of Backstage app packages (`packages/app`) who want to upgrade from the legacy frontend system to the new extension-based architecture.
 
 > **Prerequisites:**
@@ -22,10 +22,10 @@ This section describes how to migrate an existing Backstage app package to use t
 
 We recommend a **two-phase migration process** to ensure a smooth and manageable transition:
 
-- **Phase 1: Minimal Changes for Hybrid Configuration**  
+- **Phase 1: Minimal Changes for Hybrid Configuration**
   In this phase, you make the smallest set of changes necessary to enable your app to run in a hybrid mode. This allows you to start using the new frontend system while still relying on compatibility helpers and legacy code. The goal is to unblock your migration quickly, so you can benefit from the new system without a full rewrite.
 
-- **Phase 2: Complete Transition to the New Frontend System**  
+- **Phase 2: Complete Transition to the New Frontend System**
   After your app is running in hybrid mode, you can gradually refactor your codebase to remove legacy code and compatibility helpers. This phase focuses on fully adopting the new frontend architecture, ensuring your codebase is clean, maintainable, and takes full advantage of the new features.
 
 :::warning
@@ -157,36 +157,6 @@ const app = createApp({
 });
 ```
 
-If you were binding routes from a legacy `createApp`, you will need to use the `convertLegacyRouteRefs` and/or `convertLegacyRouteRef` to convert the routes to be compatible with the new system.
-
-For example, if both the `catalogPlugin` and `scaffolderPlugin` are legacy plugins, you can bind their routes like this:
-
-```ts
-import { createApp } from '@backstage/frontend-defaults';
-import {
-  // ...
-  convertLegacyRouteRefs,
-  convertLegacyRouteRef,
-} from '@backstage/core-compat-api';
-
-// Ommitting converted options changes
-//...
-
-const app = createApp({
-  features: [
-    // ...
-    convertedOptionsModule,
-  ],
-  // highlight-add-start
-  bindRoutes({ bind }) {
-    bind(convertLegacyRouteRefs(catalogPlugin.externalRoutes), {
-      createComponent: convertLegacyRouteRef(scaffolderPlugin.routes.root),
-    });
-  },
-  // highlight-add-end
-});
-```
-
 ### 3) Fixing the `app.createRoot` call
 
 The `app.createRoot(...)` no longer accepts any arguments. This represents a fundamental change that the new frontend system introduces. In the old system the app element tree that you passed to `app.createRoot(...)` was the primary way that you installed and configured plugins and features in your app. In the new system this is instead replaced by extensions that are wired together into an extension tree. Much more responsibility has now been shifted to plugins, for example you no longer have to manually provide the route path for each plugin page, but instead only configure it if you want to override the default. For more information on how the new system works, see the [architecture](../architecture/00-index.md) section.
@@ -590,21 +560,6 @@ const app = createApp({
 
 Route bindings can still be done using this option, but you now also have the ability to bind routes using static configuration instead. See the section on [binding routes](../architecture/36-routes.md#binding-external-route-references) for more information.
 
-Note that if you are binding routes from a legacy plugin that was converted using `convertLegacyAppRoot`, you will need to use the `convertLegacyRouteRefs` and/or `convertLegacyRouteRef` to convert the routes to be compatible with the new system.
-
-For example, if both the `catalogPlugin` and `scaffolderPlugin` are legacy plugins, you can bind their routes like this:
-
-```ts
-const app = createApp({
-  features: convertLegacyAppRoot(...),
-  bindRoutes({ bind }) {
-    bind(convertLegacyRouteRefs(catalogPlugin.externalRoutes), {
-      createComponent: convertLegacyRouteRef(scaffolderPlugin.routes.root),
-    });
-  },
-});
-```
-
 #### `__experimentalTranslations`
 
 Translations are now installed as extensions, created using `TranslationBlueprint`.

docs/frontend-system/building-plugins/05-migrating.md

@@ -38,7 +38,6 @@ In order to migrate the actual definition of the plugin you need to recreate the
 
 ```ts title="my-plugin/src/alpha.tsx"
   import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
-  import { convertLegacyRouteRefs } from '@backstage/core-compat-api';
 
   export default createFrontendPlugin({
     // The plugin ID is now provided as `pluginId` instead of `id`
@@ -47,15 +46,12 @@ In order to migrate the actual definition of the plugin you need to recreate the
     // bind all the extensions to the plugin
     /* highlight-next-line */
     extensions: [/* APIs will go here, but don't worry about those yet */],
-    // convert old route refs to the new system
-    /* highlight-next-line */
-    routes: convertLegacyRouteRefs({
+    routes: {
       ...
-    }),
-    /* highlight-next-line */
-    externalRoutes: convertLegacyRouteRefs({
+    },
+    externalRoutes: {
       ...
-    }),
+    },
   });
 ```
 
@@ -110,18 +106,15 @@ it can be migrated as the following, keeping in mind that you may need to switch
 
 ```tsx
 import { PageBlueprint } from '@backstage/frontend-plugin-api';
-import {
-  compatWrapper,
-  convertLegacyRouteRef,
-} from '@backstage/core-compat-api';
+import { compatWrapper } from '@backstage/core-compat-api';
 
 const fooPage = PageBlueprint.make({
   params: {
     // This is the path that was previously defined in the app code.
     // It's labelled as the default one because it can be changed via configuration.
     path: '/foo',
-    // You can reuse the existing routeRef by wrapping it with convertLegacyRouteRef.
-    routeRef: convertLegacyRouteRef(rootRouteRef),
+    // You can reuse the existing routeRef.
+    routeRef: rootRouteRef,
     // these inputs usually match the props required by the component.
     loader: () =>
       import('./components/').then(m =>