react-broadcast-sync 1.0.0 → 1.1.0

package/.eslintignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+coverage/
+demo/react-broadcast-sync/node_modules
+demo/react-broadcast-sync/dist

package/.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
     branches: [main]
 
 jobs:
-  llint-and-typecheck:
+  lint-and-typecheck:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -15,7 +15,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20.11.1
 
       - name: Install dependencies
         run: npm ci
@@ -34,7 +34,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18, 20]
+        node-version: [20.11.1]
 
     steps:
       - uses: actions/checkout@v3

package/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.11.1
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Release
+        env:
+          GH_TOKEN: ${{ secrets.GH_PAT }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.husky/pre-commit

@@ -3,4 +3,3 @@
 
 npx lint-staged
 npm run typecheck
-npm run lint-staged

package/.nvmrc

@@ -0,0 +1 @@
+20.11.1

package/.prettierignore

@@ -1,3 +1,4 @@
 node_modules
 dist
 coverage
+CHANGELOG.md

package/.prettierrc

@@ -1,5 +1,9 @@
 {
   "semi": true,
+  "tabWidth": 2,
+  "printWidth": 100,
   "singleQuote": true,
-  "trailingComma": "es5"
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "avoid"
 }

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# [1.1.0](https://github.com/IdanShalem/react-broadcast-sync/compare/v1.0.0...v1.1.0) (2025-06-03)
+
+
+### Features
+
+* added demo app deployment ([755bee2](https://github.com/IdanShalem/react-broadcast-sync/commit/755bee2c11bafcaa0653917bae8e288500f6dec6))
+
+# 1.0.0 (2025-05-30)
+
+
+### Bug Fixes
+
+* update favicon path and remove duplicate link ([c6bb7d8](https://github.com/IdanShalem/react-broadcast-sync/commit/c6bb7d85f09e36eb2e3c5da71485c247bd29ba37))
+* updated readme and fixed ci ([56d76d0](https://github.com/IdanShalem/react-broadcast-sync/commit/56d76d0ee342cce9e29968e9fb8b0fe9ee8b89fd))
+
+
+### Features
+
+* demo app ([0717637](https://github.com/IdanShalem/react-broadcast-sync/commit/07176372544f2c29ad184d8107fc176881397e5b))
+* fix ci flow ([3dfd575](https://github.com/IdanShalem/react-broadcast-sync/commit/3dfd575db288b2f1923859ccc2acc3d52de4c70c))

package/README.md

@@ -2,17 +2,57 @@
   <img src="./assets/react-broadcast-sync-logo.png" alt="react-broadcast-sync logo" width="300" />
 </p>
 
+<p align="center">
+
 # react-broadcast-sync
 
-![CI](https://github.com/IdanShalem/react-broadcast-sync/actions/workflows/ci.yml/badge.svg)
-[![codecov](https://codecov.io/gh/IdanShalem/react-broadcast-sync/branch/main/graph/badge.svg)](https://codecov.io/gh/IdanShalem/react-broadcast-sync)
-[![npm version](https://img.shields.io/npm/v/react-broadcast-sync.svg)](https://www.npmjs.com/package/react-broadcast-sync)
-[![npm downloads](https://img.shields.io/npm/dm/react-broadcast-sync.svg)](https://www.npmjs.com/package/react-broadcast-sync)
-[![bundlephobia](https://badgen.net/bundlephobia/minzip/react-broadcast-sync)](https://bundlephobia.com/result?p=react-broadcast-sync)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Issues](https://img.shields.io/github/issues/IdanShalem/react-broadcast-sync)](https://github.com/IdanShalem/react-broadcast-sync/issues)
+</p>
+
+<p align="center">
+  <a href="https://github.com/IdanShalem/react-broadcast-sync/actions/workflows/ci.yml">
+    <img alt="CI" src="https://github.com/IdanShalem/react-broadcast-sync/actions/workflows/ci.yml/badge.svg" />
+  </a>
+  <a href="https://codecov.io/gh/IdanShalem/react-broadcast-sync">
+    <img alt="Coverage" src="https://codecov.io/gh/IdanShalem/react-broadcast-sync/branch/main/graph/badge.svg" />
+  </a>
+  <a href="https://www.npmjs.com/package/react-broadcast-sync">
+    <img alt="NPM Version" src="https://img.shields.io/npm/v/react-broadcast-sync.svg" />
+  </a>
+  <a href="https://www.npmjs.com/package/react-broadcast-sync">
+    <img alt="NPM Downloads" src="https://img.shields.io/npm/dm/react-broadcast-sync.svg" />
+  </a>
+  <a href="https://bundlephobia.com/result?p=react-broadcast-sync">
+    <img alt="Bundlephobia" src="https://badgen.net/bundlephobia/minzip/react-broadcast-sync" />
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" />
+  </a>
+  <a href="https://github.com/IdanShalem/react-broadcast-sync/issues">
+    <img alt="GitHub issues" src="https://img.shields.io/github/issues/IdanShalem/react-broadcast-sync" />
+  </a>
+</p>
 
-A lightweight React hook for syncing state and communication across browser tabs using the BroadcastChannel API. This package provides a clean and type-safe abstraction over the native API, enabling efficient, scoped, and reliable cross-tab messaging.
+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](#-features)
+- [Demo App](#-demo-app)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Advanced Usage](#️-advanced-usage)
+- [BroadcastProvider](#-using-broadcastprovider)
+- [API Reference](#-api-reference)
+- [Best Practices](#-best-practices)
+- [Common Use Cases](#-common-use-cases)
+- [Performance Considerations](#-performance-considerations)
+- [Troubleshooting](#-troubleshooting)
+- [Testing](#-testing)
+- [Browser Support](#-browser-support)
+- [Coming Soon](#-coming-soon)
+- [📦 Versioning & Releases](#-versioning--releases)
+- [Contributing](#-contributing)
+- [License](#-license)
 
 ## ✨ Features
 
@@ -27,6 +67,31 @@ A lightweight React hook for syncing state and communication across browser tabs
 - ✅ Only accept allowed message types (optional)
 - 🧠 `BroadcastProvider` for context-based usage
 
+## 🎮 Demo App
+
+Check out our [live demo](https://react-broadcast-sync-3w3m.vercel.app/) 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](./demo/react-broadcast-sync-demo).
+
 ---
 
 ## 📦 Installation
@@ -49,8 +114,7 @@ pnpm add react-broadcast-sync
 import { useBroadcastChannel } from 'react-broadcast-sync';
 
 function MyComponent() {
-  const { messages, postMessage, clearMessage } =
-    useBroadcastChannel('my-channel');
+  const { messages, postMessage, clearMessage } = useBroadcastChannel('my-channel');
 
   const handleSend = () => {
     postMessage('greeting', { text: 'Hello from another tab!' });
@@ -59,7 +123,7 @@ function MyComponent() {
   return (
     <>
       <button onClick={handleSend}>Send</button>
-      {messages.map((msg) => (
+      {messages.map(msg => (
         <div key={msg.id}>
           {msg.message.text}
           <button onClick={() => clearMessage(msg.id)}>Clear</button>
@@ -98,11 +162,7 @@ const {
 #### 💬 Sending a message with expiration:
 
 ```tsx
-postMessage(
-  'notification',
-  { text: 'This disappears in 5s' },
-  { expirationDuration: 5000 }
-);
+postMessage('notification', { text: 'This disappears in 5s' }, { expirationDuration: 5000 });
 ```
 
 ---
@@ -127,7 +187,7 @@ function NotificationBar() {
 
   return (
     <div>
-      {messages.map((msg) => (
+      {messages.map(msg => (
         <p key={msg.id}>{msg.message.text}</p>
       ))}
     </div>
@@ -187,11 +247,7 @@ interface BroadcastActions {
   channelName: string; // The resolved channel name (includes namespace)
   messages: BroadcastMessage[]; // Received messages
   sentMessages: BroadcastMessage[]; // Messages sent by this instance
-  postMessage: (
-    type: string,
-    content: any,
-    options?: SendMessageOptions
-  ) => void;
+  postMessage: (type: string, content: any, options?: SendMessageOptions) => void;
   clearMessage: (id: string) => void;
   clearAllMessages: () => void;
   clearSentMessage: (id: string) => void;
@@ -261,7 +317,7 @@ function NotificationSystem() {
 
   return (
     <div>
-      {messages.map((msg) => (
+      {messages.map(msg => (
         <Notification key={msg.id} type={msg.type} content={msg.message} />
       ))}
     </div>
@@ -279,11 +335,7 @@ function FormSync() {
   });
 
   const handleChange = (field: string, value: string) => {
-    postMessage(
-      'field-update',
-      { field, value },
-      { expirationDuration: 300000 }
-    ); // 5 minutes
+    postMessage('field-update', { field, value }, { expirationDuration: 300000 }); // 5 minutes
   };
 
   return <Form onChange={handleChange} />;
@@ -310,6 +362,24 @@ function TabStatus() {
 
 ## 🔧 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
+
+### Memory Management\*\*
+
+- Clear messages when they're no longer needed
+- 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:
@@ -390,25 +460,6 @@ This will log:
 - Cleanup operations
 - Error states
 
-## ⚡ Performance Considerations
-
-1. **Message Size**
-
-   - Keep messages small and serializable
-   - Avoid sending large objects or circular references
-   - Consider using message IDs to reference larger data
-
-2. **Message Frequency**
-
-   - Use `keepLatestMessage: true` for high-frequency updates
-   - Implement debouncing for rapid state changes
-   - Consider using `expirationDuration` for temporary messages
-
-3. **Memory Management**
-   - Clear messages when they're no longer needed
-   - Use `cleaningInterval` to automatically remove expired messages
-   - Implement proper cleanup in component unmount
-
 ## 🧪 Testing
 
 ### Unit Testing
@@ -484,6 +535,25 @@ Your feedback and contributions are welcome — feel free to [open an issue](htt
 
 ---
 
+## 📦 Versioning & Releases
+
+This project uses [Semantic Release](https://semantic-release.gitbook.io/) for fully automated versioning and changelog generation.
+
+Every push to the `main` branch with a [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) message triggers a release that includes:
+
+- ✅ Automatic semantic version bump (`major`, `minor`, or `patch`)
+- ✅ Changelog generation and publishing to GitHub Releases
+- ✅ Publishing to [npm](https://www.npmjs.com/package/react-broadcast-sync)
+
+### 🔧 Example Commit Messages
+
+```bash
+feat: add support for per-type callbacks
+fix: debounce cleanup runs properly on tab reload
+chore: update dependencies
+
+---
+
 ## 🤝 Contributing
 
 PRs and feature suggestions welcome! Open an issue or submit a pull request.
@@ -493,3 +563,4 @@ PRs and feature suggestions welcome! Open an issue or submit a pull request.
 ## 🪪 License
 
 MIT © [Idan Shalem](https://github.com/IdanShalem)
+```

package/demo/react-broadcast-sync-demo/README.md

@@ -0,0 +1,130 @@
+# React Broadcast Sync Demo
+
+A showcase application demonstrating the capabilities of `react-broadcast-sync` - a library for synchronizing state across browser tabs.
+
+## 🚀 Live Demo
+
+Check out the [live demo](https://react-broadcast-sync.vercel.app) to see the synchronization in action!
+
+## 🎯 Features
+
+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
+
+## 🛠️ Technologies Used
+
+- React 19
+- TypeScript
+- Material-UI
+- Framer Motion
+- Vite
+
+## 🚀 Getting Started
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/IdanShalem/react-broadcast-sync.git
+   cd react-broadcast-sync/demo/react-broadcast-sync-demo
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Start the development server:
+
+   ```bash
+   npm run dev
+   ```
+
+4. Open multiple browser tabs to see the synchronization in action!
+
+## 📁 Project Structure
+
+```
+src/
+├── components/
+│   ├── Counter.tsx
+│   ├── TextSync.tsx
+│   └── TodoList.tsx
+├── hooks/
+│   ├── useCounterBroadcast.ts
+│   ├── useTextBroadcast.ts
+│   └── useTodoBroadcast.ts
+├── App.tsx
+├── main.tsx
+└── theme.ts
+```
+
+## 💡 Implementation Details
+
+### Counter Synchronization
+
+```typescript
+const { messages, postMessage } = useBroadcastChannel('counter', {
+  keepLatestMessage: true,
+  namespace: 'demo-app',
+});
+```
+
+### Text Synchronization
+
+```typescript
+const { messages, postMessage } = useBroadcastChannel('text', {
+  keepLatestMessage: true,
+  namespace: 'demo-app',
+});
+```
+
+### Todo List Synchronization
+
+```typescript
+const { messages, postMessage } = useBroadcastChannel('todos', {
+  keepLatestMessage: true,
+  namespace: 'demo-app',
+});
+```
+
+## 🎨 UI/UX Features
+
+- Responsive design
+- Smooth animations
+- Visual feedback for sync status
+- Modern Material-UI components
+- Dark mode support
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
+
+## 👥 Author
+
+Idan Shalem
+
+- GitHub: [@IdanShalem](https://github.com/IdanShalem)
+- LinkedIn: [Idan Shalem](https://www.linkedin.com/in/idan-shalem-3a1781169/)

package/demo/react-broadcast-sync-demo/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" href="/assets/react-broadcast-sync-logo.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>React Broadcast Sync Demo</title>
+  </head>
+
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>