Use-broadcast-ts NPM

use-broadcast-ts

GitHub Workflow Status (with branch) GitHub

Use the Broadcast Channel API in React easily with hooks or Zustand, and Typescript!

npm install use-broadcast-ts

This package allows you to use the Broadcast API with a simple hook or by using Zustand.

Checkout the demo!

Usage with Zustand

// useStore.ts
import { create } from 'zustand';
import { shared } from 'use-broadcast-ts';

type MyStore = {
    count: number;
    set: (n: number) => void;
};

const useStore = create<MyStore>(
    shared(
        (set) => ({
            count: 0,
            set: (n) => set({ count: n })
        }),
        { name: 'my-channel' }
    )
);

// MyComponent.tsx
import { FC } from 'react';

const MyComponent : FC = () => {

    const { count, set } = useStore(
        (s) => ({
            count: s.count,
            set: s.set
        })
    )

    return (
        <p>
            <p>Count: {count}</p>
            <button onClick={() => set(10)}/>
        </p>
    )
}

export default MyComponent;

You can use the Zustand store like any other Zustand store, but the store will be shared between all the tabs.

On the first "render" of the store, the middleware will check if the store already exists in another tab / window. If the store exits, it will be synchronized, else the store will be created.

If no tab is opened, the store will be created and will be shared as the "main" with the other tabs / windows.

Note: It cannot be used in server components as it needs an environment that support the Broadcast Channel API

New in v1.4.0

You don't have to specify a channel name anymore. The channel name is now automatically generated. However, I strongly recommend you to use it.

Usage with hooks

import { FC } from 'react';
import { useBroadcast } from 'use-broadcast-ts';

const MyComponent: FC = () => {
    const { state, send } = useBroadcast<{ value: number }>('my-channel', { value: 0 });

    return (
        <>
            <p>My value is: {state.value}</p>
            <button onClick={() => send({ value: 10 })} />
        </>
    );
};

export default MyComponent;

With the example above, the component will re-render when the channel receive or send a value.

import { FC, useEffect } from 'react';
import { useBroadcast } from 'use-broadcast-ts';

const MyComponent: FC = () => {
    const { send, subscribe } = useBroadcast<{ value: number }>('my-channel', { value: 0 }, { subscribe: true });

    useEffect(() => {
	    const unsub = subscribe(({ value }) => console.log(`My new value is: ${value}`));

	    return () => unsub();
    }, []);

    return (
        <>
            <button onClick={() => send({ value: 10 })} />
        </>
    );
};

export default MyComponent;

With the example above, the component will not re-render when the channel receive or send a value but will call the subscribe callback.

API

shared (Zustand)

    shared(
        (set, get, ...) => ...,
        options?: SharedOptions
    );

Parameters

options

Type: SharedOptions

The options of the hook.

options.name

Type: string

The name of the channel to use.

options.mainTimeout

Type: number (default: 100)

The timeout in ms to wait for the main tab to respond.

options.unsync

Type: boolean (default: false)

If true, the store will only synchronize once with the main tab. After that, the store will be unsynchronized.

useBroadcast (hooks)

useBroadcast<T>(name: string, value?: T, options?: UseBroadcastOptions): {
    state: T;
    send: (value: T) => void;
    subscribe: (callback: (e: T) => void) => () => void;
};