Add API docs plugin to new apps

2020-11-26 14:20:47 +01:00
parent 01ea1cc6cc
commit a00c393b38
4 changed files with 62 additions and 3 deletions
@@ -6,7 +6,66 @@ description: Documentation on How Configuring App with plugins

 ## Adding existing plugins to your app

-Coming soon!
+The following steps assumes you have created a new Backstage app and want to add
+an existing plugin to it. We are using the
+[CircleCI](https://github.com/backstage/backstage/blob/master/plugins/circleci/README.md)
+in this example.
+
+0. Add to the repo:
+
+```bash
+yarn add @backstage/plugin-circleci
+```
+
+1. Add plugin API to your Backstage instance:
+
+```js
+// packages/app/src/api.ts
+import { ApiHolder } from '@backstage/core';
+import { CircleCIApi, circleCIApiRef } from '@backstage/plugin-circleci';
+
+const builder = ApiRegistry.builder();
+builder.add(circleCIApiRef, new CircleCIApi(/* optional custom url for your own CircleCI instance */));
+
+export default builder.build() as ApiHolder;
+```
+
+2. Add plugin itself:
+
+```js
+// packages/app/src/plugins.ts
+export { plugin as Circleci } from '@backstage/plugin-circleci';
+```
+
+3. Register the plugin router:
+
+```jsx
+// packages/app/src/components/catalog/EntityPage.tsx
+
+import { Router as CircleCIRouter } from '@backstage/plugin-circleci';
+
+// Then somewhere inside <EntityPageLayout>
+<EntityPageLayout.Content
+  path="/ci-cd/*"
+  title="CI/CD"
+  element={<CircleCIRouter />}
+/>;
+```
+
+Note that stand-alone plugins that are not "attached" to the Software Catalog
+would be added outside the `EntityPage`.
+
+4. [Optional] Add proxy config:
+
+```yaml
+// app-config.yaml
+proxy:
+  '/circleci/api':
+    target: https://circleci.com/api/v1.1
+    headers:
+      Circle-Token:
+        $env: CIRCLECI_AUTH_TOKEN
+```

 ### Adding a plugin page to the Sidebar