docs: add signals plugin docs

Signed-off-by: Heikki Hellgren <heikki.hellgren@op.fi>
2023-12-05 16:03:41 +02:00
parent 59a4508efe
commit a219469cf3
4 changed files with 146 additions and 16 deletions
@@ -6,26 +6,21 @@ Signals plugin allows backend plugins to publish messages to frontend plugins.

 ## Getting started

-Add Signals router to your backend in `packages/backend/src/plugins/signals.ts`:
+First install the `@backstage/plugin-signals-node` plugin to get the `SignalService` set up.
+
+Next, add Signals router to your backend in `packages/backend/src/plugins/signals.ts`:

 ```ts
 import { Router } from 'express';
 import { createRouter } from '@backstage/plugin-signals-backend';
-import { SignalsService } from '@backstage/plugin-signals-node';
 import { PluginEnvironment } from '../types';

 export default async function createPlugin(
  env: PluginEnvironment,
 ): Promise<Router> {
-  const service = SignalsService.create({
-    logger: env.logger,
-    identity: env.identity,
-    eventBroker: env.eventBroker,
-  });
-
  return await createRouter({
    logger: env.logger,
-    service,
+    service: env.signalsService,
  });
 }
 ```
@@ -2,4 +2,69 @@

 Welcome to the Node.js library package for the signals plugin!

-_This plugin was created through the Backstage CLI_
+Signals plugin allows backend plugins to publish messages to frontend plugins.
+
+## Getting started
+
+Add SignalService to your plugin environment in `packages/backend/src/types.ts`:
+
+```ts
+import { SignalService } from '@backstage/plugin-signals-node';
+
+export type PluginEnvironment = {
+  // ...
+  signalService: SignalService;
+};
+```
+
+Add it also to your `makeCreateEnv` to allow access from the other plugins:
+
+```ts
+import { SignalService } from '@backstage/plugin-signals-node';
+import { DefaultEventBroker } from '@backstage/plugin-events-backend';
+
+function makeCreateEnv(config: Config) {
+  // ...
+
+  const eventBroker = new DefaultEventBroker(root.child({ type: 'plugin' }));
+  const signalService = SignalService.create({
+    logger: root,
+    eventBroker, // EventBroker is optional
+    identity,
+  });
+
+  return (plugin: string): PluginEnvironment => {
+    const logger = root.child({ type: 'plugin', plugin });
+    return {
+      logger,
+      eventBroker,
+      signalService,
+      // ...
+    };
+  };
+}
+```
+
+To allow connections from the frontend, you should also install the `@backstage/plugin-signals-backend`.
+
+## Using the service
+
+Once you have both of the backend plugins installed, you can utilize the signal service by calling the
+`publish` method. This will publish the message to all subscribers in the frontend. To send message to
+all subscribers, you can use `*` as `to` parameter.
+
+```ts
+// Periodic sending example
+setInterval(async () => {
+  // You can use hasSubscribers to check if the message will be sent to anyone
+  // in case you need some heavy processing before that
+  if (signalService.hasSubscribers('plugin:topic')) {
+    await signalService.publish('*', 'plugin:topic', {
+      message: 'hello world',
+    });
+  }
+}, 5000);
+```
+
+To receive this message in the frontend, check the documentation of `@backstage/plugin-signals` and
+`@backstage/plugin-signals-react`.
@@ -2,4 +2,46 @@

 Welcome to the web library package for the signals plugin!

-_This plugin was created through the Backstage CLI_
+Signals plugin allows backend plugins to publish messages to frontend plugins.
+
+## Getting started
+
+This plugin contains functionalities that help utilize the signals plugin. To get started,
+see installation instructions from `@backstage/plugin-signals-node`, `@backstage/plugin-signals-backend`, and
+`@backstage/plugin-signals`.
+
+There are two ways to utilize the signals plugin; either by using the hook or by directly using the API.
+
+## Using the hook
+
+By using the hook, unsubscribe is automatically taken care of. This helps to maintain only necessary amount
+of connections to the backend and also to allow multiple subscriptions using the same connection.
+
+Example of using the hook:
+
+```ts
+import { useSignalApi } from '@backstage/plugin-signals-react';
+
+const [message, setMessage] = useState<JsonObject | undefined>(undefined);
+useSignalApi('myplugin:topic', message => {
+  setMessage(message);
+});
+```
+
+Whenever backend publishes new message to the topic `myplugin:topic`, the state of this component is changed.
+
+## Using API directly
+
+You can also use the signal API directly. This allows more fine-grained control over the state of the connections and
+subscriptions.
+
+```ts
+import { signalsApiRef } from '@backstage/plugin-signals-react';
+
+const signals = useApi(signalsApiRef);
+signals.subscribe('myplugin:topic', (message: JsonObject) => {
+  console.log(message);
+});
+// Remember to unsubscribe
+signals.unsubscribe('myplugin:topic');
+```
@@ -2,12 +2,40 @@

 Welcome to the signals plugin!

-_This plugin was created through the Backstage CLI_
+Signals plugin allows backend plugins to publish messages to frontend plugins.

 ## Getting started

-Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/signals](http://localhost:3000/signals).
+This plugin contains client that can receive messages from the backend. To get started,
+see installation instructions from `@backstage/plugin-signals-node`, `@backstage/plugin-signals-backend`.

-You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
-This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
-It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.
+To install the plugin, you have to add the following to your `packages/app/src/plugins.ts`:
+
+```ts
+export { signalsPlugin } from '@backstage/plugin-signals';
+```
+
+And make sure that your `packages/app/src/App.tsx` contains:
+
+```ts
+import * as plugins from './plugins';
+
+const app = createApp({
+  // ...
+  plugins: Object.values(plugins),
+  // ...
+});
+```
+
+Now you can utilize the API from other plugins using the `@backstage/plugin-signals-react` package or simply by:
+
+```ts
+import { signalsApiRef } from '@backstage/plugin-signals-react';
+
+const signals = useApi(signalsApiRef);
+signals.subscribe('myplugin:topic', (message: JsonObject) => {
+  console.log(message);
+});
+// Remember to unsubscribe
+signals.unsubscribe('myplugin:topic');
+```