A patch release that fixes missing useStorage exports in subpath entries, writes during render in getSnapshot, and adds manager recycling APIs. See the changelog.
immediate now defaults to false: the value is initialized from storage instead of being written back on creation. Pass immediate: true when you need the initial value persisted immediately.ParseStrType.EVAL is deprecated: it uses new Function and throws under strict CSP (e.g. hardened Tauri or Electron). Use JSON or AUTO instead..cjs: importing through the package name or subpaths is unaffected.Old versions (v0.0.1-beta.8 and earlier):
v0.0.3+: import from the framework-specific subpath.
Legacy names such as useReactStorage are still exported as aliases but are no longer recommended.
All frameworks share BaseStoreOptions<T>:
| Property | Type | Default | Description |
|---|---|---|---|
storage |
StoreType |
StoreType.LOCAL |
Storage area: LOCAL or SESSION |
parse |
'json' | 'auto' |
'json' |
Deserialization mode |
serializer |
(value: T) => string | null | undefined |
- | Custom serializer; returning null / undefined rejects the write |
deserializer |
(raw: string) => T |
- | Custom deserializer |
version |
number |
- | Data version used together with migrate |
migrate |
(oldValue: unknown, oldVersion: number) => T |
- | Migrates old data on read and writes the result back |
equals |
(a: T, b: T) => boolean |
Reference / JSON string comparison | Skips writes and notifications when equal |
memoryFallback |
boolean |
true |
Falls back to memory when storage is unavailable or a write fails |
onError |
(ctx: StorageErrorContext) => void |
- | Error callback; ctx contains key, storage, operation, and error |
The same
key+ storage area shares one manager.optionsandinitialValueonly take effect on first creation.
json (default): strict JSON; parsing failures fall back to the initial value.auto: compatible with legacy bare strings. On read, only strings starting with {, [, or " are parsed as JSON; everything else is returned as-is. On write, strings are stored as-is and other types still use JSON.stringify.With auto, numbers and booleans are written as JSON and may come back as strings; use json when strict types matter.
The third return value in React, Preact, and Solid, and the returned object in Svelte and Vanilla expose:
| Member | Description |
|---|---|
key |
The current storage key |
remove() |
Removes the key and falls back to the initial value |
clear() |
Clears only keys managed by this library; it never calls native storage.clear() |
manager |
The underlying manager instance |
| API | Description |
|---|---|
getStorageManager(key, initialValue, options?) |
Gets or creates the shared manager for a key |
retainStorageManager(key, storage?) |
Acquires a reference; pair it with releaseStorageManager |
releaseStorageManager(key, storage?) |
Releases a reference; recycles in a microtask when the count reaches zero and there are no subscribers |
getRegisteredManagers(storage?) |
Returns registered managers |
clearManagedStorage(storage?) |
Removes all keys managed by this library |
clearStorageManagerRegistry() |
Destroys and removes every manager (for tests / HMR) |
Framework adapters automatically retain and release on mount and unmount. Manual instances and non-component scenarios must do it themselves. When using Vue outside setup, wrap the call in effectScope() and release with scope.stop().
In addition to the shared options, Vue supports:
| Property | Type | Default | Description |
|---|---|---|---|
immediate |
boolean |
false |
Writes the current value back to storage on creation |
deep |
boolean |
true |
Watches nested mutations |
Other Vue watch options are also supported.
A Ref<T> kept in sync with the selected storage area.
Built on useSyncExternalStore, with React 18+ concurrent rendering and SSR support (getInitialSnapshot() returns the initial value on the server).
[0]: the current value T[1]: updater supporting setValue(next) and setValue(prev => next)[2]: { key, remove, clear, manager }Same three-element tuple as React:
Returns [Accessor<T>, setter, StorageActions<T>]:
Returns a Svelte store with set / update / remove / clear / destroy:
Call it inside an injection context (component or service). Return value:
The manager is released when the component's DestroyRef fires.
Both the root entry and /vanilla resolve to the vanilla adapter:
| Parameter | Type | Default | Description |
|---|---|---|---|
str |
string |
- | String to parse |
type |
ParseStrType |
ParseStrType.JSON |
JSON, AUTO, or the deprecated EVAL |
ParseStrType.EVALis deprecated and throws under strict CSP. Do not use it in new code.
Checks whether storage is usable (Safari private mode, quota limits, etc.). The result is cached.
Before v0.0.1-beta.8, useStorage defaulted to immediate: true and React used a separate useReactStorage. Those interfaces are kept for compatibility only and behave differently:
useStorage default for immediate is now false.useReactStorage is now an alias of useStorage, whose return value is a three-element tuple.parseStr only supported JSON / EVAL; AUTO was added and EVAL is deprecated.New projects should use the unified APIs above.