Merge pull request #5353 from backstage/rugvip/plugins-docs

docs,READMEs: updates for composability changes

docs/features/kubernetes/installation.md

@@ -23,16 +23,8 @@ cd packages/app
 yarn add @backstage/plugin-kubernetes
 ```
 
-Once the package has been installed, you need to import the plugin in your app.
-Add the following to `packages/app/src/plugins.ts`:
-
-`plugins.ts`:
-
-```typescript
-export { plugin as Kubernetes } from '@backstage/plugin-kubernetes';
-```
-
-Now, add the "Kubernetes" tab to the catalog entity page. In
+Once the package has been installed, you need to import the plugin in your app
+by adding the "Kubernetes" tab to the catalog entity page. In
 `packages/app/src/components/catalog/EntityPage.tsx`, you'll add a router to get
 to the tab, and add the tab itself.
 

docs/features/software-catalog/installation.md

@@ -24,14 +24,8 @@ yarn add @backstage/plugin-catalog
 
 ### Adding the Plugin to your `packages/app`
 
-Add the following entry to the head of your `packages/app/src/plugins.ts`:
-
-```ts
-export { catalogPlugin } from '@backstage/plugin-catalog';
-```
-
-Next we need to install the two pages that the catalog plugin provides. You can
-choose any name for these routes, but we recommend the following:
+Add the two pages that the catalog plugin provides to your app. You can choose
+any name for these routes, but we recommend the following:
 
 ```tsx
 // packages/app/src/App.tsx

docs/features/software-templates/installation.md

@@ -26,14 +26,8 @@ yarn add @backstage/plugin-scaffolder
 
 ### Adding the Plugin to your `packages/app`
 
-Add the following entry to the head of your `packages/app/src/plugins.ts`:
-
-```ts
-export { scaffolderPlugin } from '@backstage/plugin-scaffolder';
-```
-
-Next we need to install the root page that the Scaffolder plugin provides. You
-can choose any path for the route, but we recommend the following:
+Add the root page that the Scaffolder plugin provides to your app. You can
+choose any path for the route, but we recommend the following:
 
 ```tsx
 import { ScaffolderPage } from '@backstage/plugin-scaffolder';

docs/features/techdocs/getting-started.md

@@ -29,14 +29,8 @@ yarn add @backstage/plugin-techdocs
 
 Once the package has been installed, you need to import the plugin in your app.
 
-Add the following to `packages/app/src/plugins.ts`:
-
-```typescript
-export { plugin as TechDocs } from '@backstage/plugin-techdocs';
-```
-
-Now we can add a route for the TechDocs page. In `packages/app/src/App.tsx`,
-import TechDocsPage and add the following to `FlatRoutes`:
+In `packages/app/src/App.tsx`, import `TechDocsPage` and add the following to
+`FlatRoutes`:
 
 ```tsx
 import { TechDocsPage } from '@backstage/plugin-techdocs';

docs/getting-started/configure-app-with-plugins.md

@@ -27,14 +27,7 @@ package.json. Backstage Apps are set up as monorepos with
 [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). Since
 CircleCI is a frontend UI plugin, it goes in `app` rather than `backend`.
 
-2. Add the plugin itself to the App:
-
-```js
-// packages/app/src/plugins.ts
-export { plugin as CircleCi } from '@backstage/plugin-circleci';
-```
-
-3. Register the plugin in the entity pages:
+2. Add the `EntityCircleCIContent` extension to the entity pages in the app:
 
 ```diff
  // packages/app/src/components/catalog/EntityPage.tsx

docs/overview/architecture-overview.md

@@ -67,33 +67,41 @@ is available at
 
 ### Installing plugins
 
-Plugins are typically loaded by the UI in your Backstage applications
-`plugins.ts` file. For example,
-[here](https://github.com/backstage/backstage/blob/master/packages/app/src/plugins.ts)
-is that file in the Backstage sample app.
+Plugins are typically installed as React components in your Backstage
+application. For example,
+[here](https://github.com/backstage/backstage/blob/master/packages/app/src/App.tsx)
+is a file that imports many full-page plugins in the Backstage sample app.
 
-Plugins can be enabled, and passed configuration in `apis.ts`. For example,
-[here](https://github.com/backstage/backstage/blob/master/packages/app/src/apis.ts)
-is that file in the Backstage sample app.
-
-This is how the Lighthouse plugin would be enabled in a typical Backstage
-application:
+An example of one of these plugin components is the `CatalogIndexPage`, which is
+a full-page view that allows you to browse entities in the Backstage catalog. It
+is installed in the app by importing it and adding it as an element like this:
 
 ```tsx
-import { ApiHolder, ApiRegistry } from '@backstage/core';
-import {
-  lighthouseApiRef,
-  LighthouseRestApi,
-} from '@backstage/plugin-lighthouse';
+import { CatalogIndexPage } from '@backstage/plugin-catalog';
 
-const builder = ApiRegistry.builder();
+...
 
-export const lighthouseApi = new LighthouseRestApi(/* URL of the lighthouse microservice! */);
-builder.add(lighthouseApiRef, lighthouseApi);
-
-export default builder.build() as ApiHolder;
+const routes = (
+  <FlatRoutes>
+    ...
+    <Route path="/catalog" element={<CatalogIndexPage />} />
+    ...
+  </FlatRoutes>
+);
 ```
 
+Note that we use `"/catalog"` as our path to this plugin page, but we can choose
+any route we want for the page, as long as it doesn't collide with the routes
+that we choose for the other plugins in the app.
+
+These components that are exported from plugins are referred to as "Plugin
+Extension Components", or "Extension Components". They are regular React
+components, but in addition to being able to be rendered by React, they also
+contain various pieces of metadata that is used to wire together the entire app.
+Extension components are created using `create*Extension` methods, which you can
+read more about in the
+[composability documentation](../plugins/composability.md).
+
 As of this moment, there is no config based install procedure for plugins. Some
 code changes are required.
 

docs/plugins/structure-of-a-plugin.md

@@ -100,8 +100,7 @@ There are three things needed for a Backstage app to start making use of a
 plugin.
 
 1. Add plugin as dependency in `app/package.json`
-2. `import` plugin in `app/src/plugins.ts`
-3. Import and use one or more plugin extensions, for example in
+2. Import and use one or more plugin extensions, for example in
    `app/src/App.tsx`.
 
 Luckily these three steps happen automatically when you create a plugin with the