{"id":20204400,"url":"https://github.com/efstajas/svelte-stored-writable","last_synced_at":"2025-03-15T15:07:35.468Z","repository":{"id":143287525,"uuid":"615306244","full_name":"efstajas/svelte-stored-writable","owner":"efstajas","description":"✍️💾😎 A simple drop-in extension of Svelte's writable that stores and restores its contents using localStorage.","archived":false,"fork":false,"pushed_at":"2024-09-09T08:52:30.000Z","size":21,"stargazers_count":46,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-28T20:36:35.502Z","etag":null,"topics":["localstorage","svelte","writable"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/efstajas.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":"2023-03-17T12:00:41.000Z","updated_at":"2025-01-02T04:25:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"39313a2d-0ad2-405a-83d3-e124ccdd029a","html_url":"https://github.com/efstajas/svelte-stored-writable","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efstajas%2Fsvelte-stored-writable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efstajas%2Fsvelte-stored-writable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efstajas%2Fsvelte-stored-writable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efstajas%2Fsvelte-stored-writable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/efstajas","download_url":"https://codeload.github.com/efstajas/svelte-stored-writable/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243746200,"owners_count":20341203,"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":["localstorage","svelte","writable"],"created_at":"2024-11-14T05:12:54.983Z","updated_at":"2025-03-15T15:07:35.448Z","avatar_url":"https://github.com/efstajas.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💾 Svelte Stored Writable\n\nA drop-in extension of Svelte's `writable` that additionally stores and restores its contents using localStorage. Perfect for saving local preferences and much more. Fully type-safe.\n\n## ⬇️ Installation\n\nInstall with NPM or yarn. We're also installing `zod` to be able to define the writable's schema (more on this below).\n\n```bash\nnpm install @efstajas/svelte-stored-writable zod\n\n# OR\n\nyarn add @efstajas/svelte-stored-writable zod\n```\n\n## 🤓 Usage\n\n### Creating a new storedWritable\n\nTo generate a new storedWritable, call it with a `key`, `schema` and `initialValue`:\n\n```ts\nimport storedWritable from '@efstajas/svelte-stored-writable';\nimport { z } from 'zod';\n\nconst myWritableSchema = z.object({\n  foo: z.string(),\n  bar: z.number(),\n});\n\nconst myStoredWritable = storedWritable('my-writable-key', myWritableSchema, { foo: 'hello', bar: 1234 });\n```\n\n#### `key`\n\nThe first argument, `key`, simply defines the localStorage `key` that this writable should use. Usually, you want to keep this unique between storedWritables (and other mechanisms writing to localStorage in your application) to avoid interference.\n\n#### `schema`\n\nThe `schema` argument receives a `zod` schema definition. This schema is used both to infer the writable's type for Typescript, and also to validate localStorage contents at runtime. Using the zod schema, we can ensure that the writable's contents always match the expected type definition, even if localStorage has been meddled with for some reason. This means that if you call `storedWritable` and it finds a previous value in localStorage that doesn't match the expected schema, it will throw a Zod Parse Error.\n\n#### `initialValue`\n\nWhen calling `storedWritable`, it will first attempt to restore any previously-saved content from localStorage. If it doesn't find any, it will fall back to `initialValue`. Note that writable content is only saved to localStorage on a call to `.set` or `.update`.\n\n#### Optional: `skipLocalStorage`\n\nPass `true` as the last argument to disable all interaction with localStorage. This will cause the writable to *not* attempt to restore contents from localStorage, or write any changes. You might want to set this to `true` in an SSR context, for instance, where the server has no access to `localStorage`.\n\nTip: If you're using SvelteKit, you can pass `!browser` as the last argument to automatically skip localStorage interactions while rendering server-side.\n\n### Reading from and writing to the storedWritable\n\nYou can interact with a `storedWritable` in the exact same way as a normal `writable`.\nAdditionally, you can call `storedWritable.clear` to delete any saved data in localStorage, and reset it back to `initialValues`.\n\n```ts\n// ...\n\nconst myStoredWritable = storedWritable('my-writable-key', myWritableSchema, { foo: 'hello', bar: 1234 });\n\nconst { foo, bar } = get(myStoredWritable); // foo: 'hello', bar: 1234\n\nmyStoredWritable.set({ foo: 'goodbye', bar: 1234 }); // Saves new values to localStorage\nconst { foo, bar } = get(myStoredWritable); // foo: 'goodbye', bar: 1234\n\nmyStoredWritable.update((v) =\u003e ({ ...v, bar: v.bar + 1 })); // Saves new values to localStorage\nconst { foo, bar } = get(myStoredWritable); // foo: 'goodbye', bar: 1235\n\nmyStoredWritable.clear(); // Deletes any saved data in localStorage\nconst { foo, bar } = get(myStoredWritable); // foo: 'hello', bar: 1234\n```\n\nWithin a Svelte component, you can also use the usual `$writable` syntax to conveniently subscribe to changes of a `storedWritable`.\n\n### Setting a custom writable type\n\nIf you want to use a custom TypeScript type for the storedWritable, you can pass an optional type parameter. When setting a type parameter,\nyour `schema` parameter must match the supplied type.\n\n```ts\n\nimport storedWritable from '@efstajas/svelte-stored-writable';\nimport { z } from 'zod';\n\ninterface MyWritableType {\n  foo: string;\n  bar: number;\n}\n\nconst myWritableSchema = z.object({\n  foo: z.string(),\n  bar: z.number(),\n});\n\n// myStoredWritable is typed as Writable\u003cMyWritableType\u003e. `myWritableSchema` must match `MyWritableType`.\nconst myStoredWritable = storedWritable\u003cMyWritableType\u003e('my-writable-key', myWritableSchema, { foo: 'hello', bar: 1234 });\n```\n\n### Synchronizing values between tabs\n\nThe storedWritable automatically uses [`storageEvent`](https://developer.mozilla.org/en-US/docs/Web/API/Window/storage_event) to keep changes to its localStorage key triggered from other tabs or windows synchronized.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fefstajas%2Fsvelte-stored-writable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fefstajas%2Fsvelte-stored-writable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fefstajas%2Fsvelte-stored-writable/lists"}