@typhonjs-svelte/simple-web-storage v0.5.0

Provides a set of Svelte store helper functions to connect Svelte w/ the browser web Storage API. This package is an evolution of svelte-persistent-stores for Svelte v4+. The primary reason to choose this package over alternatives is that it accomplishes the task in ~100 source lines of code w/ no dependencies besides Svelte.

API documentation

Usage

Persist to localStorage

import { writable, readable, derived } from '@typhonjs-svelte/simple-web-storage/local';

// The first argument is the storage key followed by any default value.
const count = writable('count', 0);

count.set(1);

Persist to sessionStorage

import { writable, readable, derived } from '@typhonjs-svelte/simple-web-storage/session';

// The first argument is the storage key followed by any default value.
const count = writable('count', 0);

count.set(1);

The named exports from the main package export provides localStores / sessionStores respectively containing derived / readable / writable properties.

import { localStores, sessionStores } from '@typhonjs-svelte/simple-web-storage';

// The first argument is the storage key followed by any default value.
const localCount = localStores.writable('count', 0);
const sessionCount = sessionStores.writable('count', 0);

localCount.set(1);
sessionCount.set(1);

API

The stores provided have the same signature as the Svelte store helper functions except the first argument is the string key used by localStorage and sessionStorage to store and retrieve the value. The Storage interface specification only allows string values therefore this library by default serializes stored values as JSON.

Advanced API / Customization

The storeGenerator function that wraps and creates Storage connected stores is available allowing further external customization. You may provide a custom serialization strategy that is different from JSON along with providing any Storage API compatible interface besides browser localStorage / sessionStorage. The serialize / deserialize functions must match the partial signatures of JSON.parse / JSON.stringify; IE the first value argument and return types.

The following is a Typescript example for generating storage API compatible stores w/ a customized serialization strategy:

import {
   storeGenerator,
   StorageDerived,
   StorageReadable,
   StorageWritable } from '@typhonjs-svelte/simple-web-storage/generator';

// The `storage` option for `storeGenerator` must be a Storage API compatible instance.

// Provide a JSON parse / stringify signature compatible functions to modify serialization strategy. 
// const deserialize = ... // (value: string, ...rest: any[]) => any 
// const serialize = ... // (value: any, ...rest: any[]) => string

export const localStores = storeGenerator({ storage: globalThis?.localStorage, serialize, deserialize });

export const derived: StorageDerived = localStores.derived;
export const readable: StorageReadable = localStores.readable;
export const writable: StorageWritable = localStores.writable;

Beyond the derived, readable, and writable store helper functions created storeGenerator also adds the storage, serialize, and deserialize instance / functions to the returned object.

In the package tests the custom serialization strategy tested is compressed MessagePack to base64 data.

Other Svelte browser storage packages

For more comprehensive solutions that are a bit more heavyweight check out:

• @macfja/svelte-persistent-store
• Dexie.js (IndexedDB)