docs: update plugin create and reference docs for top-level routable extensions

docs/plugins/plugin-development.md

@@ -23,35 +23,60 @@ browser APIs or by depending on external modules to do the work.
 
 ### Routing
 
-Each plugin is responsible for registering its components to corresponding
-routes in the app.
+Each plugin can export routable extensions, which are then imported into the app
+and mounted at a path.
 
-The app will call the `createPlugin` method on each plugin, passing in a
-`router` object with a set of methods on it.
+First you will need a `RouteRef` instance to serve as the mount point of your
+extensions. This can be used within your own plugin to create a link to the
+extension page using `useRouteRef`, as well as for other plugins to link to your
+extension.
 
-```jsx
+It is best to place these in a separate top-level `src/routes.ts` file, in order
+to avoid import cycles, for example like this:
+
+```tsx
+/* src/routes.ts */
+import { createRouteRef } from '@backstage/core';
+
+// Note: This route ref is for internal use only, don't export it from the plugin
+export const rootRouteRef = createRouteRef({
+  title: 'Example Page',
+});
+```
+
+Now that we have a `RouteRef`, we import it into `src/plugin.ts`, create our
+plugin instance with `createPlugin`, as well as create and wrap our routable
+extension using `createRoutableExtension` from `@backstage/core`:
+
+```tsx
+/* src/plugin.ts */
 import { createPlugin, createRouteRef } from '@backstage/core';
 import ExampleComponent from './components/ExampleComponent';
 
-export const rootRouteRef = createRouteRef({
-  path: '/new-plugin',
-  title: 'New plugin',
-});
-
-export const plugin = createPlugin({
-  id: 'new-plugin',
-  register({ router }) {
-    router.addRoute(rootRouteRef, ExampleComponent);
+// Create a plugin instance and export this from your plugin package
+export const examplePlugin = createPlugin({
+  id: 'example',
+  routes: {
+    root: rootRouteRef, // This is where the route ref should be exported for usage in the app
   },
 });
+
+// This creates a routable extension, which are typically full pages of content.
+// Each extension should also be exported from your plugin package.
+export const ExamplePage = examplePlugin.provide(
+  createRoutableExtension({
+    // The component needs to be lazy-loaded. It's what will actually be rendered in the end.
+    component: () =>
+      import('./components/ExampleComponent').then(m => m.ExampleComponent),
+    // This binds the extension to this route ref, which allows for routing within and across plugin extensions
+    mountPoint: rootRouteRef,
+  }),
+);
 ```
 
-#### `router` API
+This extension can then be imported and used in the app as follow, typically
+placed within the top-level `<FlatRoutes>`:
 
-```typescript
-addRoute(
-  target: RouteRef,
-  Component: ComponentType<any>,
-  options?: RouteOptions,
-): void;
+```tsx
+<Route route="/any-path" element={<ExamplePage />} />
 ```