persistnsync

Persist-And-Sync Zustand Store

Zustand middleware to easily persist and sync Zustand state between tabs/windows/iframes (Same Origin)

Motivation: Recently I got caught up in several issues working with the persist middleware and syncing tabs with Zustand. This is a simple lightweight middleware to persist and instantly share state between tabs or windows

• ✅ 🐙 ~ 1 kB size cross-tab state sharing + persistence for zustand
• ✅ Full TypeScript Support
• ✅ solid reliability in 1 writing and n reading tab scenarios (with changing writing tab)
• ✅ Fire and forget approach of always using the latest state. Perfect for single-user systems
• ✅ Share state between multiple browsing contexts
• ✅ Additional control over which fields to persist-and-sync and which to ignore
• ✅ Optimized for performance using memoization and closures.
• ✅ Update options at runtime by setting __persistNSyncOptions in your store.

Install

$ pnpm add persist-and-sync

or

$ npm install persist-and-sync

or

$ yarn add persist-and-sync

Usage

Add the middleware while creating the store and the rest will be taken care.

import { create } from "zustand";
import { persistNSync } from "persist-and-sync";

type MyStore = {
	count: number;
	set: (n: number) => void;
};

const useStore = create<MyStore>(
	persistNSync(
		set => ({
			count: 0,
			set: n => set({ count: n }),
		}),
		{ name: "my-example" },
	),
);

⚡🎉Boom! Just a couple of lines and your state perfectly syncs between tabs/windows and it is also persisted using localStorage!

Advanced Usage (Customizations)

PersistNSyncOptions

In several cases, you might want to exclude several fields from syncing. To support this scenario, we provide a mechanism to exclude fields based on a list of fields or regular expressions.

type PersistNSyncOptionsType = {
	name: string;
	/** @deprecated */
	regExpToIgnore?: RegExp;
	include?: (string | RegExp)[];
	exclude?: (string | RegExp)[];
	storage?: "localStorage" | "sessionStorage" | "cookies" /** Added in v1.1.0 */;
};

Example

export const useMyStore = create<MyStoreType>()(
	persistNSync(
		set => ({
			count: 0,
			_count: 0 /** skipped as it is included in exclude array */,
			setCount: count => {
				set(state => ({ ...state, count }));
			},
			set_Count: _count => {
				set(state => ({ ...state, _count }));
			},
		}),
		{ name: "example", exclude: ["_count"] },
	),
);

It is good to note here that each element of include and exclude array can either be a string or a regular expression. To use regular expression, you should either use new RegExp() or /your-expression/ syntax. Double or single quoted strings are not treated as regular expression. You can specify whether to use either "localStorage", "sessionStorage", or "cookies" to persist the state - default "localStorage". Please note that "sessionStorage" is not persisted. Hence can be used for sync only scenarios.

Updating options at runtime

Since version 1.2, you can also update the options at runTime by setting __persistNSyncOptions in your Zustand state.

Example

interface StoreWithOptions {
	count: number;
	_count: number;
	__persistNSyncOptions: PersistNSyncOptionsType;
	setCount: (c: number) => void;
	set_Count: (c: number) => void;
	setOptions: (__persistNSyncOptions: PersistNSyncOptionsType) => void;
}

const defaultOptions = { name: "example", include: [/count/], exclude: [/^_/] };

export const useStoreWithOptions = create<StoreWithOptions>(
	persistNSync(
		set => ({
			count: 0,
			_count: 0 /** skipped as it matches the regexp provided */,
			__persistNSyncOptions: defaultOptions,
			setCount: count => set(state => ({ ...state, count })),
			set_Count: _count => set(state => ({ ...state, _count })),
			setOptions: __persistNSyncOptions => set(state => ({ ...state, __persistNSyncOptions })),
		}),
		defaultOptions,
	),
);

Clear Storage

Starting from version 1.2, you can also clear the persisted data by calling clearStorage function. It takes name of your store (name passed in options while creating the store), and optional storageType parameters.

import { clearStorage } from "persist-and-sync";

...
	clearStorage("my-store", "cookies");
...

Legacy / Deprecated

Ignore/filter out fields based on regExp

In several cases, you might want to exclude several fields from syncing. To support this scenario, we provide a mechanism to exclude fields based on regExp. Just pass regExpToIgnore (optional - default -> undefined) in the options object.

// to ignore fields containing a slug
persistNSync(
    set => ({
      count: 0,
      slugSomeState: 1,
      slugSomeState2: 1,
      set: n => set({ count: n }),
    }),
    { name: "my-channel", regExpToIgnore: /slug/ },
    // or regExpToIgnore: new RegExp('slug')
    // Use full power of regExp by adding `i` and `g` flags
  ),

For more details about regExp check out - JS RegExp

Exact match

For exactly matching a parameter/field use /^your-field-name$/. ^ forces match from the first character and similarly, $ forces match until the last character.

Ignore multiple fields with exact match

use regExpToIgnore: /^(field1|field2|field3)$/

🤩 Don't forget to star this repo!

Want a hands-on course for getting started with Turborepo? Check out React and Next.js with TypeScript and The Game of Chess with Next.js, React and TypeScrypt

License

Licensed as MIT open source.

---

with 💖 by Mayank Kumar Chaudhari