effector-localstorage
v1.0.0
Published
Module for Effector for sync state with localStorage
Downloads
3,490
Maintainers
Readme
effector-localstorage
Tiny and elegant module for effector to keep store state in localStorage and synchronize changes between browser tabs.
- Small. 167 bytes (minified and compressed). Single file, no dependencies. Size Limit controls the size.
- ESM-only. It targets modern browsers and Deno. For older browsers, you will need to transpile it.
- No Build. Written with plain JavaScript, you can easily patch it locally, if you need, or make a fork and install directly from GitHub.
- TypeScript support. Even while it is written in plain JavaScript, types are included.
Install
Depending on your package manager
# using `pnpm` ↓
$ pnpm add effector-localstorage
# using `yarn` ↓
$ yarn add effector-localstorage
# using `npm` ↓
$ npm install --save effector-localstorage
CDN
In Deno and modern browsers you can load it directly from CDN:
// esm.sh
import persist from 'https://esm.sh/effector-localstorage'
// jspm.io
import persist from 'https://ga.jspm.io/npm:effector-localstorage'
Download
You can download single file and add it to your codebase manually: https://cdn.jsdelivr.net/npm/effector-localstorage/index.js
Usage
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',
})
Formulae
persist(options): void
Options
store
(Store): Store to synchronize withlocalStorage
.key
(string): Key forlocalStorage
, to store value in.def
?: (any): Default value, which will be passed tostore
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
.
Value Encoding
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:
- Only simple types supported, which are valid JSON values
- Circular references are not supported
You can read more about it on MDN.
Server-Side Rendering
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.
Complex behaviour
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'
Contributors
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!