{"id":22298348,"url":"https://github.com/chrrubin/svelte-webext-stores","last_synced_at":"2025-07-29T01:33:26.863Z","repository":{"id":44808695,"uuid":"421874974","full_name":"ChrRubin/svelte-webext-stores","owner":"ChrRubin","description":"Svelte stores that are synchronized with extension/browser storage.","archived":false,"fork":false,"pushed_at":"2023-03-22T00:13:53.000Z","size":285,"stargazers_count":6,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-08T17:47:30.556Z","etag":null,"topics":["chrome","chrome-extension","firefox","mv3","store","svelte","webext","webextension"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/ChrRubin.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":"2021-10-27T15:33:33.000Z","updated_at":"2024-08-04T05:41:21.000Z","dependencies_parsed_at":"2024-09-25T14:50:54.326Z","dependency_job_id":"29e6ea53-9772-4d95-8c6c-1dd0f7e7267f","html_url":"https://github.com/ChrRubin/svelte-webext-stores","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/ChrRubin/svelte-webext-stores","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrRubin%2Fsvelte-webext-stores","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrRubin%2Fsvelte-webext-stores/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrRubin%2Fsvelte-webext-stores/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrRubin%2Fsvelte-webext-stores/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrRubin","download_url":"https://codeload.github.com/ChrRubin/svelte-webext-stores/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrRubin%2Fsvelte-webext-stores/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267616582,"owners_count":24116155,"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","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["chrome","chrome-extension","firefox","mv3","store","svelte","webext","webextension"],"created_at":"2024-12-03T18:00:45.955Z","updated_at":"2025-07-29T01:33:26.857Z","avatar_url":"https://github.com/ChrRubin.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# svelte-webext-stores\n\nSvelte stores that are synchronized with extension storage.\n\nNote: *This library is currently in alpha development, and is subject to breaking changes with or without warning.*\n\n## Features\n\n- **Different storage types support:** `chrome.storage` (either MV2 or MV3), `browser.storage` (including [webextension-polyfill](https://github.com/mozilla/webextension-polyfill)), and even non-extension storage such as `window.localStorage` and `window.sessionStorage` are supported out of the box.\n- **Automatically synchronizes** to and from storage backend.\n- **TypeScript support:** This library is fully written in TypeScript, and the distributed package includes TypeScript declarations.\n- **Custom implementations:** Create and use your own custom storage backends or synchronized stores by implementing `IStorageBackend` or `ISyncStore` respectively.\n\n## Getting started\n\n### Installation\n\n`npm install -D svelte-webext-stores`\n\nor\n\n`yarn add -D svelte-webext-stores`\n\n### Quick Usage\n\n`storage.js`\n\n```javascript\nimport { webExtStores } from 'svelte-webext-stores';\n\n// Instantiate default store handler, which is backed by MV2 chrome.storage.local\nconst stores = webExtStores();\n// Register a new synchronized store with storage key 'count' and default value of 1\nexport const count = stores.addSyncStore('count', 1);\n```\n\n`App.svelte`\n\n```html\n\u003cscript\u003e\n  import { count } from './storage.js';\n\n  function addCount() {\n    $count += 1;\n  }\n\u003c/script\u003e\n\n\u003cbutton on:click={addCount}\u003eCount: {$count}\u003c/button\u003e\n```\n\n## Advanced Usage\n\n## Storage Backends\n\nThis library supports and exports the following storage options out of the box. To use a provided storage option, simply import it and pass it into `webExtStores`.\n\n| Storage | Description |\n| --- | --- |\n| `storageMV2` | Chrome Manifest Version 2 (callback API). |\n| `storageMV3` | Chrome Manifest Version 3 (Promise API). |\n| `storageWebExt` | Mozilla WebExtension (browser API), including [webextension-polyfill](https://github.com/mozilla/webextension-polyfill). |\n| `storageLegacy` | Legacy/non-extension storage (`localStorage` or `sessionStorage`). |\n\nTo set the storage area/type, pass the corresponding string parameter.\n\n| Storage | Allowed parameter | Default\n| --- | --- | --- |\n| `storageMV2`, `storageMV3`, `storageWebExt` | `'local'` \\| `'sync'` \\| `'managed'` | `'local'` |\n| `storageLegacy` | `'session'` \\| `'local'` | `'session'`\n\nExample:\n\n```js\nimport { webExtStores, storageWebExt } from 'svelte-webext-stores';\n\n// Uses the Mozilla WebExtension browser API in the 'sync' area.\nconst stores = webExtStores(storageWebExt('sync'));\n```\n\nMore information on the `IStorageBackend` interface that is implemented by all the above storage backends can be found [here](INTERFACES.md#istoragebackend).\n\n## Synchronized Stores\n\nAll provided synchronized stores below implements the `ISyncStore` interface. More information can be found [here](INTERFACES.md#isyncstore).\n\n### `SyncStore`\n\nStandard store that synchronizes to the storage backend. Uses Svelte `writable` to implement the Svelte store contract.\n\n```ts\nWebExtStores.addSyncStore\u003cT\u003e(\n  key: string,\n  defaultValue: T,\n  syncFromExternal = true,\n  versionedOptions?: VersionedOptions\n): SyncStore\u003cT\u003e\n```\n\n| Parameter | Description |\n| --- | --- |\n| key | Storage key |\n| defaultValue | Store's default value |\n| syncFromExternal | Whether store should be updated when storage value is updated externally |\n| versionedOptions | Enables options for migrating storage values from an older version to a newer version |\n\nAside from methods derived from `ISyncStore`, `SyncStore` also contains the following methods:\n\n| Methods | Signature | Description |\n| --- | --- | --- |\n| ready | `ready: () =\u003e Promise\u003cvoid\u003e` | Ensure that any async initialization process (such as initial update from backend) has been completed. You typically don't need to manually call this unless you wish to sync the store to the storage backend before any of `get()`, `set()`, `subscribe()` or `update()` is called. |\n| reset | `reset: () =\u003e Promise\u003cvoid\u003e` | Reset store value to default value. |\n| update | `update: (updater: (value: T) =\u003e T) =\u003e Promise\u003cvoid\u003e` | Update value using callback and inform subscribers. |\n\n### `LookupStore`\n\nSynchronized store for `Record\u003cstring, any\u003e` objects. `LookupStore` is derived from and is functionally similar to `SyncStore`, with additional convenience methods for getting and setting the stored object's property values using property keys.\n\n```ts\nWebExtStores.addLookupStore\u003cT extends Record\u003cstring, any\u003e\u003e(\n  key: string,\n  defaultValue: T,\n  syncFromExternal = true,\n  versionedOptions?: VersionedOptions\u003cT\u003e\n): LookupStore\u003cT\u003e\n```\n\n| Methods | Signature | Description |\n| --- | --- | --- |\n| getItem | `getItem: \u003cR extends T[keyof T]\u003e(key: keyof T) =\u003e Promise\u003cR\u003e` | Get property value. |\n| setItem | `setItem: \u003cV extends T[keyof T]\u003e(key: keyof T, value: V) =\u003e Promise\u003cvoid\u003e` | Set property value. |\n\nExample:\n\n```js\nimport { webExtStores } from 'svelte-webext-stores';\n\nconst stores = webExtStores();\nexport const obj = stores.addLookupStore('obj', { a: 1, b: false, c: '3' });\n\n\nconst a = await obj.getItem('a'); // Returns 1\nawait obj.setItem('b', true); // Object is now { a: 1, b: false, c: '3' }\n```\n\nYou can also easily add these convenience methods to your custom `ISyncStore` implementations. More information can be found [here](INTERFACES.md#ilookupstore).\n\n### Versioned Store Values and Migration\n\n`SyncStore` and its derivatives has the optional parameter `versionedOptions`. When the parameter is provided, it keeps track of the current store's version to enable ease of migrating values from an older store version to the current version. This can be useful to migrate breaking changes on the stored data without reseting its value to default.\n\n`VersionedOptions` properties are as follows:\n\n| Property | Type | Descrption |\n| --- | --- | --- |\n| version | number | Current version number. Do not use `-1`. |\n| seperator | string | Separator between key and version. |\n| migrations | `Map\u003cnumber, (oldValue: any) =\u003e T\u003e` | Map for migrating values. Keys are the old version to match against, and values are callbacks that accepts the value found from the given old version and returns the corresponding value for the current version. Use the key `-1` to migrate from a versionless store. |\n\nSyncStores that are provided with the `versionedOptions` parameter are stored as `${key}${seperator}${version}` internally. When an older version that matches any of the keys in the Map is found, its value is passed to the callback, the returned value is stored and the old version is removed.\n\n```js\n// Initial store\nexport const size = stores.addSyncStore('size', 500);\n\n// Example usage in svelte\nwindow.resizeTo($size, $size);\n```\n\n```js\n// To migrate to a new value, replace the old declaration\nconst sizeMigrations = new Map();\nsizeMigrations.set(-1, (oldValue) =\u003e `${oldValue}x${oldValue * 2}`);\n\nexport const size = stores.addSyncStore(\n  'size',\n  '500x1000',\n  true,\n  {\n    version: 1,\n    seperator: '$',\n    migrations: sizeMigrations\n  }\n);\n\n// Example usage in svelte\nconst [width, height] = $size.split('x');\nwindow.resizeTo(width, height);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrrubin%2Fsvelte-webext-stores","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrrubin%2Fsvelte-webext-stores","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrrubin%2Fsvelte-webext-stores/lists"}