diff --git a/plugins/signals-backend/README.md b/plugins/signals-backend/README.md index d194b852f2..1f58c1195a 100644 --- a/plugins/signals-backend/README.md +++ b/plugins/signals-backend/README.md @@ -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 { - const service = SignalsService.create({ - logger: env.logger, - identity: env.identity, - eventBroker: env.eventBroker, - }); - return await createRouter({ logger: env.logger, - service, + service: env.signalsService, }); } ``` diff --git a/plugins/signals-node/README.md b/plugins/signals-node/README.md index 55d766f9e0..abea6c6d22 100644 --- a/plugins/signals-node/README.md +++ b/plugins/signals-node/README.md @@ -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`. diff --git a/plugins/signals-react/README.md b/plugins/signals-react/README.md index 4b6b4e00bc..9bdf5e964f 100644 --- a/plugins/signals-react/README.md +++ b/plugins/signals-react/README.md @@ -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(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'); +``` diff --git a/plugins/signals/README.md b/plugins/signals/README.md index 604fa98a33..e70c1ef7d8 100644 --- a/plugins/signals/README.md +++ b/plugins/signals/README.md @@ -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'); +```