📢 channel-state

A zero-dependency, framework-agnostic state management library for synchronizing state across browser tabs and windows.

📖 Overview

channel-state is a lightweight, powerful state management library designed for modern web applications. It leverages the native BroadcastChannel API to seamlessly synchronize state across all browser contexts (tabs, windows, iframes) of the same origin. With an optional persistence layer using IndexedDB, it ensures your application's state can be restored across sessions, providing a fluid user experience.

Built with TypeScript and with zero external dependencies, channel-state offers a minimal footprint and maximum flexibility. It includes dedicated, easy-to-use wrappers for popular frameworks like React, Vue, and Svelte, making integration a breeze.

📑 Table of Contents

• Common Use Cases
• Key Features
• Packages
• Installation
• CDN Usage
• Contributing
• License

🎯 Common Use Cases

• Shopping Carts: Keep a user's shopping cart synchronized across multiple tabs. If they add an item in one tab, it instantly appears in all others.
• Real-time Notifications: Display notifications (e.g., "You have a new message") across all open tabs simultaneously.
• User Authentication: When a user logs in or out in one tab, automatically update the authentication state in all other tabs.
• Collaborative Tools: In simple collaborative applications, synchronize form data or other shared state between users on the same machine.
• Feature Flags & Settings: Update application settings or feature flags in one tab and have them apply everywhere immediately.

✨ Key Features

• Real-time Cross-Context Synchronization: Automatically syncs state across all tabs and windows using the BroadcastChannel API.
• Optional State Persistence: Persist state to IndexedDB to restore it after page reloads or browser restarts.
• Framework-Agnostic Core: The @channel-state/core package works with any JavaScript project.
• Official Framework Wrappers: Idiomatic and optimized integrations for React, Vue, and Svelte.
• Zero Dependencies: The core library is incredibly lightweight with no third-party dependencies.
• TypeScript Native: Written entirely in TypeScript for robust type safety.

📦 Packages

This repository is a monorepo containing the following packages:

Package	Version	Description
@channel-state/core		The core, framework-agnostic library.
@channel-state/react		React hooks for channel-state.
@channel-state/vue		Vue composables for channel-state.
@channel-state/svelte		Svelte stores for channel-state.

🛠️ Installation

npm

# Install the core library
npm install @channel-state/core

# Install for React
npm install @channel-state/core @channel-state/react

# Install for Vue
npm install @channel-state/core @channel-state/vue

# Install for Svelte
npm install @channel-state/core @channel-state/svelte

yarn

# Install the core library
yarn add @channel-state/core

# Install for React
yarn add @channel-state/core @channel-state/react

# Install for Vue
yarn add @channel-state/core @channel-state/vue

# Install for Svelte
yarn add @channel-state/core @channel-state/svelte

pnpm

# Install the core library
pnpm add @channel-state/core

# Install for React
pnpm add @channel-state/core @channel-state/react

# Install for Vue
pnpm add @channel-state/core @channel-state/vue

# Install for Svelte
pnpm add @channel-state/core @channel-state/svelte

bun

# Install the core library
bun add @channel-state/core

# Install for React
bun add @channel-state/core @channel-state/react

# Install for Vue
bun add @channel-state/core @channel-state/vue

# Install for Svelte
bun add @channel-state/core @channel-state/svelte

For detailed usage, please refer to the README file of the specific package you are using.

🌐 CDN Usage

For direct browser usage, you can use the UMD builds from a CDN like jsDelivr or unpkg. For detailed instructions and the required script tags for each package, please see the "CDN Usage" section in the respective package's README:

• @channel-state/core README
• @channel-state/react README
• @channel-state/vue README
• @channel-state/svelte README

🚀 Playground

Explore and experiment with channel-state in a live environment using our interactive playground.

• React Channel State Demo

This playground provides a simple example of how to use @channel-state/core and @channel-state/react together.

Note: To see the cross-tab state synchronization in action, open the preview in a new tab.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines to get started. All contributors are expected to adhere to our Code of Conduct.

📜 License

This project is licensed under the Apache-2.0 License.