{"id":13492819,"url":"https://github.com/ilyalesik/effector-localstorage","last_synced_at":"2025-12-15T14:38:42.870Z","repository":{"id":36068372,"uuid":"189754306","full_name":"ilyalesik/effector-localstorage","owner":"ilyalesik","description":"Tiny and elegant module for Effector to keep store state in localStorage and synchronize changes between browser tabs","archived":false,"fork":false,"pushed_at":"2025-02-11T18:06:29.000Z","size":272,"stargazers_count":31,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-02T12:12:42.085Z","etag":null,"topics":["effector","localstorage"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ilyalesik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-01T16:25:09.000Z","updated_at":"2024-12-18T09:30:50.000Z","dependencies_parsed_at":"2023-01-16T12:46:03.724Z","dependency_job_id":"c9f0bd80-7e7b-4465-9bcb-e462c9a20e58","html_url":"https://github.com/ilyalesik/effector-localstorage","commit_stats":{"total_commits":80,"total_committers":6,"mean_commits":"13.333333333333334","dds":0.5875,"last_synced_commit":"382816f2ba598495dbb4598d18699df7e2688c53"},"previous_names":["lessmess-dev/effector-localstorage"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilyalesik%2Feffector-localstorage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilyalesik%2Feffector-localstorage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilyalesik%2Feffector-localstorage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ilyalesik%2Feffector-localstorage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ilyalesik","download_url":"https://codeload.github.com/ilyalesik/effector-localstorage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248054205,"owners_count":21039952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["effector","localstorage"],"created_at":"2024-07-31T19:01:09.511Z","updated_at":"2025-12-15T14:38:37.812Z","avatar_url":"https://github.com/ilyalesik.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# effector-localstorage\n\n[![Tests Status](https://github.com/ilyalesik/effector-localstorage/workflows/test/badge.svg)](https://github.com/ilyalesik/effector-localstorage/actions?workflow=test)\n[![License](https://img.shields.io/github/license/ilyalesik/effector-localstorage.svg?color=yellow)](./LICENSE)\n[![NPM](https://img.shields.io/npm/v/effector-localstorage.svg)](https://www.npmjs.com/package/effector-localstorage)\n[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg)](#contributors)\n![Made with Love](https://img.shields.io/badge/made%20with-❤-red.svg)\n\nTiny and elegant module for effector to keep store state in [localStorage] and synchronize changes between browser tabs.\n\n- **Small.** 167 bytes (minified and compressed). Single file, no dependencies. [Size Limit](https://github.com/ai/size-limit) controls the size.\n- **ESM-only.** It targets modern browsers and Deno. For older browsers, you will need to transpile it.\n- **No Build.** Written with plain JavaScript, you can easily patch it locally, if you need, or make a fork and install directly from GitHub.\n- **TypeScript support.** Even while it is written in plain JavaScript, types are included.\n\n## Install\n\nDepending on your package manager\n\n```bash\n# using `pnpm` ↓\n$ pnpm add effector-localstorage\n\n# using `yarn` ↓\n$ yarn add effector-localstorage\n\n# using `npm` ↓\n$ npm install --save effector-localstorage\n```\n\n#### CDN\n\nIn Deno and modern browsers you can load it directly from CDN:\n\n```javascript\nimport persist from 'https://esm.sh/effector-localstorage'\n```\n\n#### Download\n\nYou can download single file and add it to your codebase manually:\u003cbr\u003e\nhttps://cdn.jsdelivr.net/npm/effector-localstorage/index.js\n\n## Usage\n\n```javascript\nimport { createStore, createEvent } from 'effector'\nimport persist from 'effector-localstorage'\n\nconst inc = createEvent()\nconst dec = createEvent()\nconst $counter = createStore(0)\n  .on(inc, (state) =\u003e state + 1)\n  .on(dec, (state) =\u003e state - 1)\n\n// persist store in `localStorage`\npersist({\n  store: $counter,\n  key: 'counter',\n})\n```\n\nYou can play with this example in [Effector's Playground](https://share.effector.dev/MEwiE0j6).\n\n## Formulae\n\n- `persist(options): void`\n\n### Options\n\n- `store` ([_Store_]): Store to synchronize with `localStorage`.\n- `key` ([_string_]): Key for `localStorage`, to store value in.\n- `def`?: (_any_): Default value, which will be passed to `store` in case of absent storage value. Default = `store.defaultState`.\n- `fail`? ([_Event_] | [_Effect_]): Event or Effect, which will be triggered in case of any error (serialization/deserialization error, storage is full and so on).\n- `sync`? ([_boolean_]): Add [`'storage'`] event listener or no. Default = `true`.\n\n## Value Encoding\n\n[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.\n\n`effector-localstorage` uses [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) for serialization and [`JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) for deserialization.\u003cbr\u003e\nYou cannot change it.\n\nThese methods has some limitations, because of JSON specification:\n\n- Only simple types supported, which are valid JSON values\n- Circular references are not supported\n\nYou can read more about it on [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description).\n\n## Server-Side Rendering\n\nWhile 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.\n\nNote though, that you will probably want to add `serialize:'ignore'` to persisted stores, so server value will not interfere with browser value.\n\n## Complex behaviour\n\n`effector-localstorage` [does one thing well](https://en.wikipedia.org/wiki/Unix_philosophy), and we would like to leave this package in its \"state of an art\" status.\n\nThe only valid reason to increase package size — is to fix an issue, but not new functionality.\n\nIf you know, how to reduce package size without breaking tests — PRs are welcome :)\n\nIf 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`](https://github.com/yumauri/effector-storage) package.\n\n`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:\n\n```diff\n- import persist from 'effector-localstorage'\n+ import { persist } from 'effector-storage/local'\n```\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://twitter.com/ilialesik\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/1270648?v=4?s=100\" width=\"100px;\" alt=\"Ilya Lesik\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eIlya Lesik\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ilyalesik/effector-localstorage/commits?author=ilyalesik\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://stackoverflow.com/users/388916/hubro\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/597206?v=4?s=100\" width=\"100px;\" alt=\"Tomas Sandven\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eTomas Sandven\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ilyalesik/effector-localstorage/commits?author=Hubro\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/yumauri\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/6583994?v=4?s=100\" width=\"100px;\" alt=\"Victor Didenko\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eVictor Didenko\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ilyalesik/effector-localstorage/commits?author=yumauri\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n[localstorage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage\n[`'storage'`]: https://developer.mozilla.org/en-US/docs/Web/API/StorageEvent\n[_effect_]: https://effector.dev/docs/api/effector/effect\n[_event_]: https://effector.dev/docs/api/effector/event\n[_store_]: https://effector.dev/docs/api/effector/store\n[_string_]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\n[_function_]: https://developer.mozilla.org/en-US/docs/Glossary/Function\n[_boolean_]: https://developer.mozilla.org/en-US/docs/Glossary/Boolean\n[_error_]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filyalesik%2Feffector-localstorage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filyalesik%2Feffector-localstorage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filyalesik%2Feffector-localstorage/lists"}