Storage
createStorage returns a typed mirror of localStorage / sessionStorage, limited to the
keys you declare:
import { createStorage, date, json, number, oneOf, string } from 'parsistent';
import { z } from 'zod';
export const local = createStorage('local', {
theme: oneOf(['light', 'dark'], 'light'),
count: number(0),
name: string(), // no default: reads as string | null
lastVisit: date(new Date(0)),
filters: json(z.object({ q: z.string() }), { q: '' }),
});Methods
local.getItem('theme'); // 'light' | 'dark'
local.setItem('count', 3); // stored as '3'
local.removeItem('count'); // reads as 0 again
local.clear(); // removes only the declared keys
local.length; // number of declared keys that are set
local.key(0); // 'theme' | 'count' | … | null
local.setItem('count', '3'); // ❌ type error
local.setItem('nope', 1); // ❌ type errorInvalid values read as the default
Storage can contain anything. When a stored value doesn’t parse, getItem returns the
default instead:
local.getItem('count') → 0Behaviour
- Setting the default removes the key, to keep storage clean. Pass
{ clearOnDefault: false }to keep it. 'local'/'session'resolve lazily, so stores can be created at module level in server-rendered apps. You can also pass anyStorageobject, or a function returning one.- On the server, reads return defaults and writes are ignored, so values never leak between requests.
- Blocked storage (disabled site data, some private modes) falls back to memory with a warning, instead of throwing.
- Full storage: like
localStorage.setItem,setItemthrows when the quota is exceeded.
Change events
local.addEventListener('change', (event) => {
event.key; // 'count'
event.oldValue; // 0
event.newValue; // 3
event.external; // true when the change came from another tab
});Unlike the native storage event, it also fires for changes made in the current tab, and only
when the parsed value actually changes.
Options
createStorage('local', schema, {
prefix: 'my-app:', // stored as 'my-app:count'
clearOnDefault: true,
});Last updated on