Tiny and elegant module for Effector to keep store state in localStorage and synchronize changes between browser tabs
MIT License
Tiny and elegant module for effector to keep store state in localStorage and synchronize changes between browser tabs.
Depending on your package manager
# using `pnpm` ↓
$ pnpm add effector-localstorage
# using `yarn` ↓
$ yarn add effector-localstorage
# using `npm` ↓
$ npm install --save effector-localstorage
In Deno and modern browsers you can load it directly from CDN:
import persist from 'https://esm.sh/effector-localstorage'
You can download single file and add it to your codebase manually: https://cdn.jsdelivr.net/npm/effector-localstorage/index.js
import { createStore, createEvent } from 'effector'
import persist from 'effector-localstorage'
const inc = createEvent()
const dec = createEvent()
const $counter = createStore(0)
.on(inc, (state) => state + 1)
.on(dec, (state) => state - 1)
// persist store in `localStorage`
persist({
store: $counter,
key: 'counter',
})
You can play with this example in Effector's Playground.
persist(options): void
store
(Store): Store to synchronize with localStorage
.key
(string): Key for localStorage
, to store value in.def
?: (any): Default value, which will be passed to store
in case of absent storage value. Default = store.defaultState
.fail
? (Event | Effect): Event or Effect, which will be triggered in case of any error (serialization/deserialization error, storage is full and so on).sync
? (boolean): Add 'storage'
event listener or no. Default = true
.LocalStorage supports storing only plain strings. Because of that it is required to do value serialization for persisting and string deserialization for restoring the value, if your value is more complex, than just plain string.
effector-localstorage
uses JSON.stringify
for serialization and JSON.parse
for deserialization.
You cannot change it.
These methods has some limitations, because of JSON specification:
You can read more about it on MDN.
While you can use effector-localstorage
in SSR environment, this will not throw an exception in runtime, BUT persist
function will trigger fail
(if you passed it) if localStorage
and/or addEventListener
are not available. If your business logic does not rely on fail
, you can safely ignore this behaviour — persist
will do nothing with store value on server side.
Note though, that you will probably want to add serialize:'ignore'
to persisted stores, so server value will not interfere with browser value.
effector-localstorage
does one thing well, and we would like to leave this package in its "state of an art" status.
The only valid reason to increase package size — is to fix an issue, but not new functionality.
If you know, how to reduce package size without breaking tests — PRs are welcome :)
If your business logic requires more complex behaviour, like custom serialization/deserialization, support for sessionStorage
or other storages, like IndexedDB
, or reactive pick-ups from non-reactive storage — take a look on effector-storage
package.
effector-localstorage
's API was intentionally changed in order for effector-storage
to be "drop-in" replacement for it. You can just replace import and here you go, ready to enrich your application:
- import persist from 'effector-localstorage'
+ import { persist } from 'effector-storage/local'
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!