Merge pull request #1930 from spotify/ndudnik/register-component-readme

docs: register component plugin
2020-08-12 16:13:58 +02:00
parent 359594f9d3 e53cfe1569
commit d74066d045
6 changed files with 88 additions and 1 deletions
@@ -1,5 +1,92 @@
-# [WIP] register-component
+# Register component plugin

 Welcome to the register-component plugin!

 This plugin allows you to submit your Backstage component using your software's YAML config.
+
+When installed it is accessible on [localhost:3000/register-component](localhost:3000/register-component).
+
+<img src="./src/assets/screenshot-1.png" />
+<img src="./src/assets/screenshot-2.png" />
+<img src="./src/assets/screenshot-3.png" />
+<img src="./src/assets/screenshot-4.png" />
+<img src="./src/assets/screenshot-5.png" />
+
+## Standalone setup
+
+0. Install plugin and its dependency `plugin-catalog`
+
+```bash
+yarn add @backstage/plugin-register-component -W
+yarn add @backstage/plugin-catalog -W
+```
+
+1. Add dependencies to the active plugins list
+
+```typescript
+// packages/app/src/plugins.ts
+export { plugin as RegisterComponent } from '@backstage/plugin-register-component';
+export { plugin as CatalogPlugin } from '@backstage/plugin-catalog';
+```
+
+2. Create `packages/app/src/apis.ts` and register all the needed plugins
+
+```typescript
+import {
+  alertApiRef,
+  AlertApiForwarder,
+  ApiRegistry,
+  ConfigApi,
+  errorApiRef,
+  ErrorApiForwarder,
+  ErrorAlerter,
+} from '@backstage/core';
+
+import { catalogApiRef, CatalogClient } from '@backstage/plugin-catalog';
+
+export const apis = (config: ConfigApi) => {
+  const backendUrl = config.getString('backend.baseUrl');
+
+  const builder = ApiRegistry.builder();
+
+  const alertApi = builder.add(alertApiRef, new AlertApiForwarder());
+  const errorApi = builder.add(
+    errorApiRef,
+    new ErrorAlerter(alertApi, new ErrorApiForwarder()),
+  );
+
+  builder.add(
+    catalogApiRef,
+    new CatalogClient({
+      apiOrigin: backendUrl,
+      basePath: '/catalog',
+    }),
+  );
+
+  return builder.build();
+};
+```
+
+3. Pass `apis` to createApp
+
+```typescript
+// packages/app/src/App.tsx
+import { apis } from './apis';
+
+const app = createApp({
+  apis,
+  plugins: Object.values(plugins),
+});
+```
+
+## Running
+
+Just run the backstage.
+
+```
+yarn start && yarn --cwd packages/backend start
+```
+
+## Usage
+
+Pretty straightforward, navigate to [localhost:3000/register-component](localhost:3000/register-component) and enter your component's YAML config URL.