Enforcing RouteRefs more: docs, templates, types

docs/getting-started/structure-of-a-plugin.md

@@ -43,13 +43,19 @@ In the root folder you have some configuration for typescript and jest, the test
 In the `src` folder we get to the interesting bits. Check out the `plugin.ts`:
 
 ```jsx
-import { createPlugin } from '@backstage/core';
+import { createPlugin, createRouteRef } from '@backstage/core';
 import ExampleComponent from './components/ExampleComponent';
 
-export default createPlugin({
-  id: 'new-plugin',
+export const rootRouteRef = createRouteRef({
+  icon: () => null,
+  path: '/{{ id }}',
+  title: '{{ id }}',
+});
+
+export const plugin = createPlugin({
+  id: '{{ id }}',
   register({ router }) {
-    router.registerRoute('/new-plugin', ExampleComponent);
+    router.addRoute(rootRouteRef, ExampleComponent);
   },
 });
 ```

docs/reference/createPlugin-router.md

@@ -1,21 +1,48 @@
 # createPlugin - router
 
-The router that is passed to the `register` function includes makes it possible for plugins to hook into routing of the Backstage app and provide the end users with new views to navigate to.
+The router that is passed to the `register` function makes it possible for plugins to hook into routing of the Backstage app and provide the end users with new views to navigate to.
+This is done by utilising the following methods on the `router`:
 
 ```typescript
-type RouterHooks = {
-  registerRoute(
-    path: RoutePath,
-    Component: ComponentType<any>,
-    options?: RouteOptions,
-  ): void;
+addRoute(
+  target: RouteRef,
+  Component: ComponentType<any>,
+  options?: RouteOptions,
+): void;
 
-  registerRedirect(
-    path: RoutePath,
-    target: RoutePath,
-    options?: RouteOptions,
-  ): void;
-};
+addRedirect(from: RouteRef, to: RouteRef, options?: RouteOptions): void;
+
+/**
+ * @deprecated See the `addRoute` method
+ */
+registerRoute(
+  path: RoutePath,
+  Component: ComponentType<any>,
+  options?: RouteOptions,
+): void;
+
+/**
+ * @deprecated See the `addRedirect` method
+ */
+registerRedirect(
+  path: RoutePath,
+  target: RoutePath,
+  options?: RouteOptions,
+): void;
+```
+
+## RouteRef
+
+Both `addRoute` and `addRedirect` methods are using mutable RouteRefs, which can be created as following:
+
+```ts
+import { createRouteRef } from '@backstage/core';
+
+const myPluginRouteRef = createRouteRef({
+  icon: () => null, // You can set an icon for your route
+  path: '/my-plugin',
+  title: 'My Plugin',
+});
 ```
 
 [Back to References](README.md)

packages/cli/templates/default-plugin/src/plugin.ts.hbs

@@ -14,12 +14,18 @@
  * limitations under the License.
  */
 
-import { createPlugin } from '@backstage/core';
+import { createPlugin, createRouteRef } from '@backstage/core';
 import ExampleComponent from './components/ExampleComponent';
 
+export const rootRouteRef = createRouteRef({
+  icon: () => null,
+  path: '/{{ id }}',
+  title: '{{ id }}',
+});
+
 export const plugin = createPlugin({
   id: '{{ id }}',
   register({ router }) {
-    router.registerRoute('/{{ id }}', ExampleComponent);
+    router.addRoute(rootRouteRef, ExampleComponent);
   },
 });

packages/core-api/src/app/App.tsx

@@ -110,7 +110,7 @@ export class PrivateAppImpl implements BackstageApp {
             );
             break;
           }
-          case 'redirect-route': {
+          case 'legacy-redirect-route': {
             const { path, target, options = {} } = output;
             const { exact = true } = options;
             routes.push(
@@ -118,6 +118,19 @@ export class PrivateAppImpl implements BackstageApp {
             );
             break;
           }
+          case 'redirect-route': {
+            const { from, to, options = {} } = output;
+            const { exact = true } = options;
+            routes.push(
+              <Redirect
+                key={from.path}
+                path={from.path}
+                to={to.path}
+                exact={exact}
+              />,
+            );
+            break;
+          }
           case 'feature-flag': {
             registeredFeatureFlags.push({
               pluginId: plugin.getId(),

packages/core-api/src/plugin/Plugin.tsx

@@ -42,12 +42,20 @@ export type RouterHooks = {
     options?: RouteOptions,
   ): void;
 
+  addRedirect(from: RouteRef, to: RouteRef, options?: RouteOptions): void;
+
+  /**
+   * @deprecated See the `addRoute` method
+   */
   registerRoute(
     path: RoutePath,
     Component: ComponentType<any>,
     options?: RouteOptions,
   ): void;
 
+  /**
+   * @deprecated See the `addRedirect` method
+   */
   registerRedirect(
     path: RoutePath,
     target: RoutePath,
@@ -88,11 +96,24 @@ export class PluginImpl {
             options,
           });
         },
+        addRedirect(from, to, options) {
+          outputs.push({
+            type: 'redirect-route',
+            from,
+            to,
+            options,
+          });
+        },
         registerRoute(path, component, options) {
           outputs.push({ type: 'legacy-route', path, component, options });
         },
         registerRedirect(path, target, options) {
-          outputs.push({ type: 'redirect-route', path, target, options });
+          outputs.push({
+            type: 'legacy-redirect-route',
+            path,
+            target,
+            options,
+          });
         },
       },
       featureFlags: {

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

@@ -41,6 +41,13 @@ export type RouteOutput = {
 
 export type RedirectRouteOutput = {
   type: 'redirect-route';
+  from: RouteRef;
+  to: RouteRef;
+  options?: RouteOptions;
+};
+
+export type LegacyRedirectRouteOutput = {
+  type: 'legacy-redirect-route';
   path: RoutePath;
   target: RoutePath;
   options?: RouteOptions;
@@ -56,6 +63,7 @@ export type FeatureFlagOutput = {
 export type PluginOutput =
   | LegacyRouteOutput
   | RouteOutput
+  | LegacyRedirectRouteOutput
   | RedirectRouteOutput
   | FeatureFlagOutput;