Merge pull request #30689 from backstage/rugvip/route-alias

frontend-plugin-api: add aliasFor option to createRouteRef

docs/frontend-system/architecture/36-routes.md

@@ -419,3 +419,42 @@ export default createFrontendPlugin({
   extensions: [catalogIndexPage],
 });
 ```
+
+## Route Aliases - Overriding Routed Extensions in Modules
+
+It is possible to [override extensions of a plugin using a module](./25-extension-overrides.md#creating-a-frontend-module). In some cases the extension you're overriding may require a route reference. You could import import the plugin instance and access the it via the `routes` property, but this creates a direct dependency on the plugin and risks leading to package duplication issues that would also break the route reference.
+
+Instead of accessing the route reference directly, you can create a new route reference that acts as an alias for the original one from the plugin. For example, you can override the catalog index page with a custom one like this:
+
+```tsx
+const indexRouteRef = createRouteRef({ aliasFor: 'catalog.catalogIndex' });
+
+export default createFrontendModule({
+  pluginId: 'catalog',
+  extensions: [
+    PageBlueprint.make({
+      params: {
+        defaultPath: '/catalog',
+        routeRef: indexRouteRef,
+        loader: () =>
+          import('./CustomCatalogIndexPage').then(m => (
+            <m.CustomCatalogIndexPage />
+          )),
+      },
+    }),
+  ],
+});
+```
+
+Aliases are limited to the plugin that they are defined in. These aliases can also be imported and used as usual with for example `useRouteRef`, but they must always be registered in the app via an extension for this to work. For example, the following will not work:
+
+```tsx
+function MyInvalidComponent() {
+  // This is NOT valid
+  const link = useRouteRef(
+    createRouteRef({ aliasFor: 'catalog.catalogIndex' }),
+  );
+
+  // ...
+}
+```