npm install hydrate-storage

Node 18+ for tooling and SSR; any browser with the Web Storage API. react (18+) and vue (3.3+) are optional peer dependencies, needed only for the matching subpath.

import { createStorage } from 'hydrate-storage'import { z } from 'zod' export const storage = createStorage({  namespace: 'myapp',  onError: (error) => logger.warn(error.code, error.message),}) export const settings = storage.item('settings', {  defaultValue: { theme: 'light' as 'light' | 'dark' },  schema: z.object({ theme: z.enum(['light', 'dark']) }),  version: 2,  migrate: (old, from) => (from === 1 ? { theme: old } : old),  ttl: 7 * 24 * 60 * 60 * 1000,}) settings.get()settings.set({ theme: 'dark' })settings.set((prev) => ({ ...prev, theme: 'light' }))settings.remove()settings.subscribe(() => console.log(settings.get()))

Any Standard Schema library works (Zod 3.24+, Valibot, ArkType). Schemas must be synchronous.

'use client'import { useStorageItem } from 'hydrate-storage/react'import { settings } from './storage' export function ThemeToggle() {  const [value, setSettings] = useStorageItem(settings)  return (    <button onClick={() => setSettings({ theme: value.theme === 'dark' ? 'light' : 'dark' })}>      {value.theme}    </button>  )}

useStorageItem is built on useSyncExternalStore with a server snapshot. In the App Router, hooks live in Client Components; the storage module itself can be imported from Server Components.

import { useStorageItem } from 'hydrate-storage/vue' const settings = useStorageItem(settingsItem)settings.value = { theme: 'dark' }

Returns a writable computed. It starts at defaultValue to match server HTML and syncs with storage in onMounted.

<script>  import { settings } from './storage'  const store = settings.asStore()</script> <button on:click={() => store.set({ theme: 'dark' })}>{$store.theme}</button>

asStore() implements the Svelte store contract. On the server the first emission is defaultValue.

item.get, item.set and item.subscribe(listener) are enough to build a binding. subscribe returns an unsubscribe function and getServerSnapshot is available for SSR-aware stores.

When schema is set it runs on every read and every write. Invalid writes are rejected and set returns false. Invalid stored data is reported and defaultValue is returned; the bad entry stays in storage until the next successful write.

Every entry records the version it was written with (default 1). Migrations are applied lazily on read; the upgraded form is written on the next set.

ttl is in milliseconds and counted from the last write. Expired entries read as missing and has() is false for them. They are not deleted on read; call storage.purgeExpired(), for example on app start, to reclaim space.

In the browser, if Web Storage is blocked or throws (private mode, sandboxed iframes, disabled cookies) the adapter falls back to in-memory storage for the page's lifetime. On the server every built-in adapter except memory is a no-op.

No method throws on storage problems. Failures are passed to onError as a StorageError with a code, the full namespaced key and the original cause.

createStorage, createMemoryAdapter, noopAdapter, createWebAdapter, createCookieAdapter, StorageError and the types StorageAdapter, Serializer, Codec, StorageOptions, ItemOptions, StorageItem, Storage, StorageErrorCode, AdapterKind, CookieOptions and StandardSchemaV1. Subpaths: hydrate-storage/react and hydrate-storage/vue, each exporting useStorageItem.

The server never reads cookies. If a value must be known during SSR, such as a theme, read it with your framework's cookie API and pass it as the render input.

• Everything is synchronous; async backends (IndexedDB, React Native AsyncStorage) and async schemas are not supported.
• Web Storage is limited to a few MB per origin and cookies to about 4 KB per entry.
• Cross-tab sync works for adapters that provide subscribe: local, and custom adapters.
• Expired entries are removed only by purgeExpired() or by overwriting them.
• Do not store secrets or session tokens in JavaScript-readable storage. Use HttpOnly cookies for those.

MIT licensed. Full README, changelog and issue tracker are on GitHub (opens in a new tab); the package is on npm (opens in a new tab).