effector-localstorage

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

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):

Ilya Lesik 💻

Tomas Sandven 💻

Victor Didenko 💻

This project follows the all-contributors specification. Contributions of any kind welcome!