@syncrelay/react

SyncRelay SDK for React

Disclaimer: This package is still in preview and may change substantially until a stable version is released.

The SyncRelay SDK for React provides all the tools you need to create reactive user interfaces with SyncRelay.

Getting started

The SDK provides a hook that manages the complete connection lifecycle, useSyncRelay.

The following example will establish a connection to your project's Live Endpoint and receive messages to the topic /example.

Before we can initiate our connection, we need to obtain a consumer token. Depending on your environment, the process to getting this will look different, you can check out our example with Next.js for reference.

Once you have obtained a consumer token, and passed it to the current component, all you have to do is to call the hook, pass in your Live Endpoint URL copied from the project overview, and watch new messages come in, appended to a list kept in the current component's state.

import { useSyncRelay, ReceivedMessage } from '@syncrelay/react';

const [messages, setMessages] = useState<ReceivedMessage<unknown>[]>([]);
const [connectionState] = useSyncRelay(
  {
    receivedMessage: (message) => {
      setMessages((prev) => [message, ...prev]);
    },
  },
  {
    liveUrl,
    subscribeTo: [`/example`],
    consumerToken,
  }
);

Reference

useSyncRelay

The useSyncRelay hook accepts an object of lifecycle hooks that are invoked whenever the respective event occurs, and options, including which topics to subscribe to, the live URL, and the consumer token.

Once rendered, the browser will establish a connection to the SyncRelay infrastructure and subscribe to the passed topics. Health checks are automatically taken care of, received messages are delegated to the receivedMessage hook.

If you want to close the connection, simply stop rendering the component including hook. This will close existing connections, after which no more activity happens.