persist-and-sync
v1.2.1
Published
Zustand middleware to easily persist and sync Zustand state between tabs and windows
Downloads
5,232
Maintainers
Readme
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
andexclude
array can either be a string or a regular expression. To use regular expression, you should either usenew 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.