persist-valtio

name	persist-valtio
description	Persist a valtio proxy object with @stainless-code/persist (persistProxy). Use when wiring valtio state to localStorage/sessionStorage/IndexedDB via snapshot/subscribe.
license	MIT
metadata	{"type":"composition","library":"@stainless-code/persist","library_version":"0.4.1","framework":"valtio"}
sources	["stainless-code/persist:src/adapters/sources/valtio.ts","stainless-code/persist:docs/architecture.md"]

Persisting valtio

@stainless-code/persist/sources/valtio maps a proxy object through snapshot / Object.assign / subscribe (valtio/vanilla) onto persistSource.

When to use this skill

• You have a proxy({…}) object state and want it to survive reload.
• State is an object (not a primitive proxy target).

Install

bun add @stainless-code/persist valtio

valtio is an optional peer of /sources/valtio.

Minimal wiring

import { proxy } from "valtio";
import { createJSONStorage } from "@stainless-code/persist";
import { persistProxy } from "@stainless-code/persist/sources/valtio";

const prefs = proxy({ theme: "light" as const });
const persist = persistProxy(prefs, {
  name: "app:prefs:v1",
  storage: createJSONStorage(() => localStorage),
});

Hydrate semantics

Writes apply with Object.assign(proxy, next) — keys absent from next are not deleted. Design partialize / migrate so hydrate payloads carry the shape you need, or reset keys yourself.

Common mistakes

• Persisting a non-object. TState extends object.
• Expecting deep replace / key deletion on hydrate via assign alone.
• Forgetting destroy() for non-singleton proxies.

API surface

• persistProxy(proxyObject, options) → PersistApi
• Options / PersistApi: same as persistSource

See also: persist-mobx — same object + assign pattern with runInAction.