Registry / web-framework / persist-and-sync

persist-and-sync

library1.2.3jsnpmunverified

Zustand middleware for persisting and syncing state across browser tabs, windows, and iframes (same origin). Current stable version is 1.2.3, released regularly with a focus on reliability. It uses the Broadcast Channel API for instant cross-tab synchronization and localStorage (or sessionStorage/cookies) for persistence. Differentiators include sub-1kB size, full TypeScript support, fire-and-forget state updates optimized for single-user systems, and exclude/include filters for selective syncing. Alternatives like zustand's built-in persist middleware lack cross-tab sync out of the box.

web-framework database

npm install persist-and-sync

github ↗package ↗

INSTALL

IMPORT

SIG · PERSIST-AND-SYNC

persist-and-sync

web-frameworkjavascriptv1.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.

persistNSync

✓ import { persistNSync } from 'persist-and-sync'

✗ import persistNSync from 'persist-and-sync'

This is a named export, not a default export.

PersistNSyncOptions

✓ import type { PersistNSyncOptions } from 'persist-and-sync'

✗ import { PersistNSyncOptions } from 'persist-and-sync'

This type is only available as a type export for TypeScript. Use 'import type' to avoid emitting runtime code.

persistNSync (CommonJS)

✓ const { persistNSync } = require('persist-and-sync')

✗ const persistNSync = require('persist-and-sync')

CommonJS require must destructure the named export.

Creates a Zustand store with persistNSync middleware; state is persisted to localStorage and synced across tabs.

import { create } from 'zustand'; import { persistNSync } from 'persist-and-sync'; type MyStore = { count: number; increment: () => void; }; const useStore = create<MyStore>( persistNSync( (set) => ({ count: 0, increment: () => set((state) => ({ count: state.count + 1 })), }), { name: 'counter-storage' } ) ); // In a React component: function Counter() { const { count, increment } = useStore(); return <button onClick={increment}>Count: {count}</button>; }

Debug

Known issues

gotchaThe middleware uses BroadcastChannel API which requires same-origin browsing contexts. It will not work across different origins.

fix

Ensure all tabs/windows are on the same origin (protocol, host, port).

affects: >=1.0.0

gotchaWhen using 'sessionStorage' for storage, the state is not persisted across sessions but still syncs across tabs within the same session.

fix

Use 'localStorage' (default) if you need persistence across browser restarts.

affects: >=1.1.0

deprecatedThe 'regExpToIgnore' option is deprecated since v1.2.0. Use 'exclude' with regex patterns instead.

fix

Replace 'regExpToIgnore: /pattern/' with 'exclude: [/pattern/]' in the options object.

affects: >=1.2.0

gotchaIn a scenario with multiple writing tabs, only the last writing tab's state wins (fire-and-forget). This middleware is designed for single-user systems.

fix

For collaborative editing or multi-writer conflicts, consider a different sync strategy or backend.

affects: >=1.0.0

gotchaThe middleware does not support partial syncing of nested state; include/exclude filters only apply to top-level keys.

fix

Flatten nested state or create separate stores for subsets you want to filter.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'persist-and-sync' or its corresponding type declarations.

Missing installation or TypeScript cannot locate types.

fix

Run 'npm install persist-and-sync' and ensure tsconfig.json includes 'node_modules' in 'typeRoots' or uses a bundler that resolves types.

TypeError: persistNSync is not a function

Incorrect import: default import instead of named import.

fix

Change to 'import { persistNSync } from 'persist-and-sync';'

Property 'persistNSync' does not exist on type 'typeof import("persist-and-sync")'.

CommonJS require without destructuring.

fix

Use 'const { persistNSync } = require('persist-and-sync');'

Uncaught DOMException: Failed to construct 'BroadcastChannel': The origin 'null' is not allowed.

Running from file:// protocol (e.g., opening HTML directly). BroadcastChannel requires http:// or https:// origin.

fix

Serve the app via a local dev server (e.g., 'npx serve .' or use a framework dev server).

Upgrade

Version history

1.2.3latest on npm

Audit

Dependencies

zustandrequiredPeer dependency - middleware designed for zustand stores

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/react18-tools/persist-and-sync ↗

packagehttps://www.npmjs.com/package/persist-and-sync ↗