react-broadcast-sync

Easily sync UI state or user events across browser tabs in React apps — notifications, presence, forms, and more. This package provides a clean and type-safe abstraction over the native API, enabling efficient, scoped, and reliable cross-tab messaging.

Table of Contents

• Features
• Demo App
• Installation
• Quick Start
• Advanced Usage
• BroadcastProvider
• API Reference
• Best Practices
• Common Use Cases
• Performance Considerations
• Troubleshooting
• Testing
• Browser Support
• Coming Soon
• Versioning & Releases
• Contributing
• License

Features

• Simple and intuitive API
• Real-time synchronization across tabs
• TypeScript support
• Zero dependencies
• Automatic message expiration and cleanup
• Send/receive any serializable message
• Namespace and source scoping support
• Clear individual or all messages
• Only accept allowed message types (optional)
• BroadcastProvider for context-based usage
• Ping and active source detection (discover other tabs and their source names)

Demo App

Check out our live demo to see the library in action! The demo showcases three main features:

1. Counter Synchronization

   • Real-time counter updates across tabs
   • Visual feedback for sync status
   • Smooth animations

2. Text Synchronization

   • Real-time text input sync
   • Multi-line support
   • Instant updates

3. Todo List

   • Synchronized todo items
   • Real-time hover effects
   • Scroll position sync
   • Completion status sync
   • Delete functionality

The demo is built with React 19, TypeScript, Material-UI, and Framer Motion. You can find the source code in the demo directory.

---

Installation

1npm install react-broadcast-sync
2# or
3yarn add react-broadcast-sync
4# or
5pnpm add react-broadcast-sync

---

Quick Start

Basic Usage

1import { useBroadcastChannel } from 'react-broadcast-sync';
2
3function MyComponent() {
4  const { messages, postMessage, clearReceivedMessages } = useBroadcastChannel('my-channel');
5
6  const handleSend = () => {
7    postMessage('greeting', { text: 'Hello from another tab!' });
8  };
9
10  return (
11    <>
12      <button onClick={handleSend}>Send</button>
13      {messages.map(msg => (
14        <div key={msg.id}>
15          {msg.message.text}
16          <button onClick={() => clearReceivedMessages({ ids: [msg.id] })}>Clear</button>
17        </div>
18      ))}
19    </>
20  );
21}

---

Advanced Usage

1const {
2  channelName,
3  messages,
4  sentMessages,
5  postMessage,
6  clearReceivedMessages,
7  clearSentMessages,
8  error,
9} = useBroadcastChannel('my-channel', {
10  sourceName: 'my-tab',
11  cleaningInterval: 2000,
12  keepLatestMessage: true,
13  registeredTypes: ['greeting', 'notification'],
14  namespace: 'my-app',
15  deduplicationTTL: 10 * 60 * 1000, // 10 minutes
16  cleanupDebounceMs: 500, // Debounce cleanup operations by 500ms
17});

Sending a message with expiration:

1postMessage('notification', { text: 'This disappears in 5s' }, { expirationDuration: 5000 });

---

Using BroadcastProvider

You can wrap part of your app with BroadcastProvider and use useBroadcastProvider() to consume the channel context.

1import { BroadcastProvider, useBroadcastProvider } from 'react-broadcast-sync';
2
3function App() {
4  return (
5    <BroadcastProvider channelName="notifications">
6      <NotificationBar />
7    </BroadcastProvider>
8  );
9}
10
11function NotificationBar() {
12  const { messages } = useBroadcastProvider();
13
14  return (
15    <div>
16      {messages.map(msg => (
17        <p key={msg.id}>{msg.message.text}</p>
18      ))}
19    </div>
20  );
21}

---

API Reference

useBroadcastChannel Hook

1const {
2  channelName,
3  messages,
4  sentMessages,
5  postMessage,
6  clearReceivedMessages,
7  clearSentMessages,
8  error,
9} = useBroadcastChannel(channelName, options);

Options

1interface BroadcastOptions {
2  sourceName?: string; // Custom name for the message source
3  cleaningInterval?: number; // Interval in ms for cleaning expired messages (default: 1000)
4  keepLatestMessage?: boolean; // Keep only the latest message (default: false)
5  registeredTypes?: string[]; // List of allowed message types
6  namespace?: string; // Channel namespace for isolation
7  deduplicationTTL?: number; // Time in ms to keep message IDs for deduplication (default: 5 minutes)
8  cleanupDebounceMs?: number; // Debounce time in ms for cleanup operations (default: 0)
9  batchingDelayMs?: number; // Delay in ms to batch outgoing messages (default: 20). If > 0, messages are batched and sent together.
10  excludedBatchMessageTypes?: string[]; // Message types to always send immediately, never batched (default: []).
11}

Default Values

Option	Default Value	Description
sourceName	undefined	Auto-generated if not provided
cleaningInterval	1000	1 second between cleanup runs
keepLatestMessage	false	Keep all messages by default
registeredTypes	[]	Accept all message types by default
namespace	''	No namespace by default
deduplicationTTL	300000	5 minutes (5 _ 60 _ 1000 ms)
cleanupDebounceMs	0	No debounce by default
batchingDelayMs	20	Batch delay in ms (0 = off)
excludedBatchMessageTypes	[]	Types never batched

Return Value

1interface BroadcastActions {
2  channelName: string; // The resolved channel name (includes namespace)
3  messages: BroadcastMessage[]; // Received messages
4  sentMessages: BroadcastMessage[]; // Messages sent by this instance
5  postMessage: (type: string, content: any, options?: SendMessageOptions) => void;
6  clearReceivedMessages: (opts?: { ids?: string[]; types?: string[]; sources?: string[] }) => void;
7  clearSentMessages: (opts?: { ids?: string[]; types?: string[]; sync?: boolean }) => void;
8  getLatestMessage: (opts?: { type?: string; source?: string }) => BroadcastMessage | null;
9  closeChannel: () => void;
10  error: string | null; // Current error state
11}

useBroadcastChannel(channelName, options?)

Returns an object with:

Property	Type	Description
channelName	string	The resolved channel name (includes namespace)
messages	BroadcastMessage[]	All received messages from other tabs
sentMessages	BroadcastMessage[]	Messages sent from this tab
postMessage()	function	Send a message to all tabs
clearReceivedMessages()	function	Clear received messages. No filters ⇒ clear all. With filters, a message is deleted only if it matches every provided filter (ids, types, sources). Empty arrays act as wildcards.
clearSentMessages()	function	Clear messages this tab sent (same matching rules). Pass sync: true to broadcast the clear to other tabs.
getLatestMessage()	function	Get the latest message matching optional filters (type, source). Returns the most recent message that matches, or null if none.
ping(timeoutMs?)	function	Ping other tabs on the channel and collect their source names. timeoutMs (default: 300ms) controls how long to wait for responses before resolving. Returns a Promise of string array.
isPingInProgress	boolean	true while a ping is active, otherwise false.
closeChannel()	function	Explicitly closes the broadcast channel and removes event listeners. Safe to call multiple times.
error	string | null	Any runtime error from the channel

Clearing examples

1// Clear everything we've received
2clearReceivedMessages();
3
4// Clear all messages we sent and broadcast the clear to other tabs
5clearSentMessages({ sync: true });
6
7// Clear by id or by type (OR inside each array)
8clearReceivedMessages({ ids: ['123'] }); // id match
9clearReceivedMessages({ types: ['alert', 'chat'] }); // type match
10
11// Combine filters (logical AND between filters)
12// Removes messages whose id is '123' AND type is 'alert'
13clearSentMessages({ ids: ['123'], types: ['alert'] });

Send Options:

1interface SendMessageOptions {
2  expirationDuration?: number; // TTL in ms
3  expirationDate?: number; // Exact expiry timestamp
4}

Message Format:

1interface BroadcastMessage {
2  id: string;
3  type: string;
4  message: any;
5  timestamp: number;
6  source: string;
7  expirationDate?: number;
8}

Getting the Latest Message

You can use getLatestMessage to retrieve the most recent message received, optionally filtered by type and/or source. If no options are provided, it returns the latest message of any kind. If no message matches, it returns null.

Signature:

1getLatestMessage(options?: { type?: string; source?: string }): BroadcastMessage | null

Examples:

1// Get the latest message of any type/source
2const latest = getLatestMessage();
3
4// Get the latest message of a specific type
5const latestAlert = getLatestMessage({ type: 'alert' });
6
7// Get the latest message from a specific source
8const latestFromTab = getLatestMessage({ source: 'tab-123' });
9
10// Get the latest message of a specific type from a specific source
11const latestInfoFromTab = getLatestMessage({ type: 'info', source: 'tab-123' });
12
13// Check if there are any messages of a type
14if (getLatestMessage({ type: 'notification' })) {
15  // ...
16}

Behavior:

• If no messages are present, returns null.
• If no message matches the filter, returns null.
• If multiple messages match, returns the most recently received one.

Ping & Active Source Detection

useBroadcastChannel provides a ping method and an isPingInProgress state for discovering active sources (tabs) on the same channel.

• ping(timeoutMs?: number): Promise<string[]>: Broadcasts a ping and collects responses from other tabs within the timeout. Returns an array of source names (excluding your own).
• isPingInProgress: boolean: Indicates if a ping is currently in progress.

Example:

1const { ping, isPingInProgress } = useBroadcastChannel('my-channel', {
2  sourceName: 'my-tab',
3});
4
5// To discover other active sources:
6const activeSources = await ping(300); // e.g., ['tab-2', 'tab-3']
7
8// To show loading state:
9if (isPingInProgress) {
10  // Show spinner or status
11}

Closing the Channel Explicitly

You can use closeChannel to explicitly close the underlying BroadcastChannel and remove all event listeners. This is useful if you want to clean up resources before the component unmounts, or to stop all cross-tab communication on demand. Note that the channel will automatically close and all event listeners will be removed when the component unmounts, so this method is mainly useful for manual cleanup.

Signature:

1closeChannel(): void

Example:

1const { closeChannel } = useBroadcastChannel('my-channel');
2
3// ... later, when you want to stop all communication:
4closeChannel();

Notes:

• After calling closeChannel, the channel is closed and will not send or receive any more messages.
• It is safe to call closeChannel multiple times (idempotent).
• You do not need to call this for normal React unmounting; the hook will clean up automatically. Use it for explicit/manual cleanup only.

---

Best Practices

• Use namespace to isolate functionality between different app modules.
• Register allowed message types using registeredTypes to avoid processing unknown or irrelevant messages.
• Always handle error state in UI or logs to detect channel failures.
• Use keepLatestMessage: true if you only care about the most recent message (e.g. status updates).
• Set appropriate deduplicationTTL based on your message frequency and importance.
• Use cleanupDebounceMs when dealing with rapid message updates to prevent performance issues.

Common Use Cases

Real-time Notifications

1function NotificationSystem() {
2  const { messages, postMessage } = useBroadcastChannel('notifications', {
3    keepLatestMessage: true,
4    registeredTypes: ['alert', 'info', 'warning'],
5    deduplicationTTL: 60000, // 1 minute
6  });
7
8  return (
9    <div>
10      {messages.map(msg => (
11        <Notification key={msg.id} type={msg.type} content={msg.message} />
12      ))}
13    </div>
14  );
15}

Multi-tab Form Synchronization

1function FormSync() {
2  const { messages, postMessage } = useBroadcastChannel('form-sync', {
3    namespace: 'my-form',
4    cleaningInterval: 5000,
5  });
6
7  const handleChange = (field: string, value: string) => {
8    postMessage('field-update', { field, value }, { expirationDuration: 300000 }); // 5 minutes
9  };
10
11  return <Form onChange={handleChange} />;
12}

Tab Status Synchronization

1function TabStatus() {
2  const { postMessage } = useBroadcastChannel('tab-status', {
3    sourceName: 'main-tab',
4    keepLatestMessage: true,
5  });
6
7  useEffect(() => {
8    postMessage('tab-active', { timestamp: Date.now() });
9    return () => postMessage('tab-inactive', { timestamp: Date.now() });
10  }, []);
11
12  return null;
13}

Performance Considerations

Message Size

• Keep messages small and serializable
• Avoid sending large objects or circular references
• Consider using message IDs to reference larger data

Message Frequency

• Use keepLatestMessage: true for high-frequency updates
• Implement debouncing for rapid state changes
• Consider using expirationDuration for temporary messages

Batching Mechanism

Batching allows you to group multiple outgoing messages and send them together in a single post to the BroadcastChannel. This can significantly reduce the number of cross-tab events, improve performance, and avoid flooding the channel when many messages are sent in rapid succession (e.g., during fast typing or bulk updates).

• batchingDelayMs: If set to a value greater than 0 (default: 20ms), outgoing messages are collected for up to this delay and then sent as an array. If 0 or negative, batching is disabled and all messages are sent immediately.
• excludedBatchMessageTypes: An array of message types that should always be sent immediately, even if batching is enabled. Use this for urgent or high-priority messages (e.g., 'alert', 'sync-now').

How it works:

• When batching is enabled, calls to postMessage within the batching window are buffered and sent as a batch (array of messages) after the delay.
• On the receiving side, the hook automatically handles both single messages and batches (arrays). If you listen to the channel directly, always check if Array.isArray(event.data).
• If the tab unmounts or the channel closes, any unsent batched messages are flushed immediately.

Why batching matters:

• Reduces the number of events and improves efficiency, especially for high-frequency updates.
• Prevents message storms that can occur when many updates happen in a short time.
• Lets you control which messages are always sent immediately for real-time needs.

Example:

1const { postMessage } = useBroadcastChannel('my-channel', {
2  batchingDelayMs: 50, // Batch messages for up to 50ms
3  excludedBatchMessageTypes: ['alert'], // Always send 'alert' immediately
4});
5
6// These will be batched if sent within 50ms
7postMessage('edit', { field: 'a', value: 1 });
8postMessage('edit', { field: 'b', value: 2 });
9// This will be sent immediately
10postMessage('alert', { message: 'Something happened!' });

Memory Management

• Clear messages when they're no longer needed using clearReceivedMessages / clearSentMessages
• Use cleaningInterval to automatically remove expired messages
• Implement proper cleanup in component unmount

Message Deduplication

The deduplicationTTL option creates a time window (in milliseconds) during which messages with the same content and type from the same source are considered duplicates and will be ignored. This is particularly useful for:

• Preventing Message Loops: Avoids infinite message echo between tabs when they broadcast the same message back and forth
• Reducing Redundancy: Filters out identical messages sent in rapid succession, preventing unnecessary processing
• Natural Debouncing: Provides built-in debouncing behavior for broadcast events without additional code

Recommended TTL values based on use case:

• High-frequency updates (e.g., real-time typing, cursor position): 1000-5000ms
• Medium-frequency updates (e.g., form sync, status changes): 5000-15000ms
• Low-frequency updates (e.g., notifications, alerts): 15000-30000ms

Example:

1// Without deduplication, this could cause a message loop
2function ChatComponent() {
3  const { postMessage } = useBroadcastChannel('chat', {
4    deduplicationTTL: 5000, // Ignore duplicate messages for 5 seconds
5  });
6
7  const handleMessage = (text: string) => {
8    postMessage('chat-message', { text });
9  };
10}

Cleanup Optimization

• Use cleanupDebounceMs to prevent excessive cleanup operations
• Recommended values:
  • For frequent updates: 500-1000ms
  • For infrequent updates: 0ms (no debounce)
• Adjust cleaningInterval based on your message expiration needs

Troubleshooting

Common Issues

1. Messages Not Received

   • Check if registeredTypes includes your message type
   • Verify the channel name and namespace match
   • Ensure the message hasn't expired
   • Check if deduplicationTTL isn't too short

2. Performance Issues

   • Increase cleanupDebounceMs if cleanup is too frequent
   • Use keepLatestMessage: true for high-frequency updates
   • Consider increasing cleaningInterval if cleanup is too aggressive

3. Memory Leaks

   • Ensure proper cleanup in component unmount
   • Use message expiration for temporary data
   • Clear messages when they're no longer needed

Debug Mode

Enable debug logging by setting the environment variable:

1REACT_APP_DEBUG_BROADCAST=true

This will log:

• Channel creation and closure
• Message sending and receiving
• Cleanup operations
• Error states

Testing

Unit Testing

1import { renderHook, act } from '@testing-library/react-hooks';
2import { useBroadcastChannel } from 'react-broadcast-sync';
3
4test('should send and receive messages', () => {
5  const { result } = renderHook(() => useBroadcastChannel('test-channel'));
6
7  act(() => {
8    result.current.postMessage('test', { data: 'hello' });
9  });
10
11  expect(result.current.messages).toHaveLength(1);
12  expect(result.current.messages[0].message.data).toBe('hello');
13});

Integration Testing

1import { render, screen } from '@testing-library/react';
2import { BroadcastProvider } from 'react-broadcast-sync';
3
4test('should render messages from provider', () => {
5  render(
6    <BroadcastProvider channelName="test-channel">
7      <TestComponent />
8    </BroadcastProvider>
9  );
10
11  // Your test assertions here
12});

---

Browser Support

Relies on BroadcastChannel API:

• ✅ Chrome 54+
• ✅ Firefox 38+
• ✅ Edge 79+
• ✅ Safari 15.4+
• ✅ Opera 41+

---

Coming Soon

We're actively improving react-broadcast-sync! Here are some features and enhancements planned for upcoming versions:

• Integration Tests
  Ensure robust behavior and edge-case coverage.

• Automatic Channel Recovery
  Reconnect automatically if the BroadcastChannel gets disconnected or closed by the browser.

• clearMessagesByType()
  Clear all messages of a specific type with a single call.

• Per-Type Callbacks
  Define message handlers for specific types with onMessage({ type, callback }).

• clearAllSentMessages() / clearAllReceivedMessages()
  Fine-grained control for clearing messages based on source.

We're committed to keeping this package lightweight, flexible, and production-ready.
Your feedback and contributions are welcome — feel free to open an issue!

---

Versioning & Releases

This project uses Semantic Release for fully automated versioning and changelog generation.

Every push to the main branch with a Conventional Commit message triggers a release that includes:

• ✅ Automatic semantic version bump (major, minor, or patch)
• ✅ Changelog generation and publishing to GitHub Releases
• ✅ Publishing to npm

Example Commit Messages

1feat: add support for per-type callbacks
2fix: debounce cleanup runs properly on tab reload
3chore: update dependencies
4
5---
6
7## Contributing
8
9PRs and feature suggestions welcome! Open an issue or submit a pull request.
10
11---
12
13## License
14
15MIT © [Idan Shalem](https://github.com/IdanShalem)