Registry / http-networking / zustand-sync-tabs

zustand-sync-tabs

library0.2.3jsnpmunverified

zustand-sync-tabs is a lightweight (~1KB minzipped) middleware for Zustand that facilitates seamless state synchronization across multiple browser tabs, windows, and iframes, provided they share the same origin. The current stable version is 0.2.3. It offers a 'fire and forget' setup, making it ideal for single-user applications that need consistent state across browsing contexts. Key differentiators include its small bundle size, full TypeScript support, and robust handling of one-writer/many-reader scenarios. It leverages the Broadcast Channel API (or localStorage fallback) for communication and supports both full and partial state sharing via include/exclude options for specific fields.

http-networking web-framework

npm install zustand-sync-tabs

github ↗package ↗

INSTALL

IMPORT

SIG · ZUSTAND-SYNC-TABS

zustand-sync-tabs

http-networkingjavascriptv0.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

syncTabs

✓ import { syncTabs } from 'zustand-sync-tabs';

✗ const { syncTabs } = require('zustand-sync-tabs');

Primarily designed for ESM environments; CommonJS require is generally discouraged in modern Zustand setups, especially with TypeScript.

MyStore

✓ import { create } from 'zustand'; import { syncTabs } from 'zustand-sync-tabs'; type MyStore = { count: number; set: (n: number) => void; };

When using TypeScript, it's crucial to define your store's type for correct inference and strong typing within the middleware.

This quickstart demonstrates how to integrate `zustand-sync-tabs` middleware with a Zustand store. It shows a basic store definition, the application of `syncTabs` middleware with a channel name, and how to optionally exclude specific fields from synchronization. The store's `count` will sync across tabs, while `text` will remain local.

import { create } from 'zustand'; import { syncTabs } from 'zustand-sync-tabs'; type MyStore = { count: number; text: string; setCount: (n: number) => void; setText: (s: string) => void; }; const useStore = create<MyStore>()( syncTabs( (set) => ({ count: 0, text: 'Hello from main tab', setCount: (n) => set({ count: n }), setText: (s) => set({ text: s }), }), { name: 'my-shared-channel', exclude: ['text'] // Example: Exclude 'text' from syncing } ) ); // Example usage in a component or script: // const count = useStore((state) => state.count); // const setCount = useStore((state) => state.setCount); // console.log('Current count:', count);

Debug

Known issues

deprecatedThe `regExpToIgnore` option in SyncTabsOptionsType is deprecated and will be removed in future versions. Users should migrate to the `exclude` option, which accepts an array of strings or RegExp patterns for more flexible filtering.

fix

Replace `regExpToIgnore: /pattern/` with `exclude: [/pattern/]` or `exclude: ['fieldName']` in your `syncTabs` options.

affects: >=0.2.0

gotchaState synchronization is limited to tabs/windows/iframes that share the 'same origin'. Cross-origin communication is not supported due to browser security restrictions (e.g., between `example.com` and `sub.example.com` unless specifically configured via `document.domain`).

fix

Ensure all browsing contexts requiring synchronization are hosted on the exact same origin (protocol, host, and port).

affects: >=0.1.0

gotchaIf using this middleware in combination with `zustand/persist`, ensure `syncTabs` is applied *inside* `persist` or configured carefully. The README recommends `persist-and-sync` if local persistence and cross-tab sync are both required, suggesting potential interaction complexities if managed independently.

fix

For persistence and cross-tab sync, consider using `persist-and-sync` or carefully test the order of middleware application. A common pattern is `create(persist(syncTabs(...)))` or `create(syncTabs(persist(...)))` depending on desired interaction, but using a dedicated solution might be simpler.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'getState')

The `syncTabs` middleware expects a valid Zustand store creator function as its first argument.

fix

Ensure `syncTabs` wraps your store's `(set) => ({ ... })` definition correctly, e.g., `create(syncTabs(set => ({ ... }), { name: '...' }))`.

State not syncing between tabs/windows.

This usually indicates that the 'name' option provided to `syncTabs` middleware is not identical across all browsing contexts, or the contexts are not on the same origin.

fix

Verify that the `name` property in the `syncTabs` options is an exact match (case-sensitive) for all instances of your store across different tabs. Also, confirm that all tabs are on the 'same origin'.

Upgrade

Version history

0.2.3latest on npm

Audit

Dependencies

zustandrequiredCore state management library that this package extends as a middleware.

Agent activity

46 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/react18-tools/zustand-sync-tabs ↗

packagehttps://www.npmjs.com/package/zustand-sync-tabs ↗