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)