Custom persistence backend
A browser or server application needs persistence through a storage backend other than the default local storage.
Zustand · Pipe
getStorage option
getStorage is the lazy callback used by createJSONStorage to obtain a custom storage engine. The engine must provide getItem, setItem, and removeItem; the helper returns a persistence-ready storage object.
How it works
getStorage is the callback supplied to createJSONStorage. Zustand invokes it lazily to obtain a storage engine implementing getItem, setItem, and removeItem, then wraps that engine in a JSON-compatible persistence storage for the persist middleware.
Syntax
createJSONStorage(getStorage: () => StateStorage, options?: JsonStorageOptions): StateStorageParameters
| Name | Type | Description |
|---|---|---|
getStorage | () => StateStorage | Callback that returns the underlying storage engine implementing StateStorage. |
options | JsonStorageOptions | Optional JSON-storage configuration. |
Returns
A PersistStorage object suitable for use as the storage option of persist.
Key points
- The option is a lazy provider, not the storage engine itself.
- The returned engine needs the three operations used by persistence.
- The callback's return type is the middleware's
StateStorageinterface. createJSONStorageconverts the custom engine into a persistence-ready storage object.- It supports alternatives to browser local storage, including application-specific backends.
- The engine returned by the callback is responsible for the actual storage operations.
Common mistakes
- The callback must return an object implementing all three storage methods; returning the storage object itself instead of a function does not match the signature.
- Use this option for a custom engine rather than assuming the callback itself performs serialization or persistence.
Example: Custom storage with createJSONStorage
import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
const memory = new Map<string, string>()
const storage = {
getItem: (name: string) => memory.get(name) ?? null,
setItem: (name: string, value: string) => { memory.set(name, value) },
removeItem: (name: string) => { memory.delete(name) },
}
const useStore = create(
persist(
(set) => ({ count: 0, inc: () => set((s) => ({ count: s.count + 1 })) }),
{ name: 'counter', storage: createJSONStorage(() => storage) },
),
)
useStore.getState().inc()
console.log(useStore.getState().count)
Creates a persist-compatible custom storage and supplies it lazily to createJSONStorage.
When to use it
Database or async storage
An application uses an asynchronous or database-backed storage adapter.
Lazy storage initialization
Storage APIs should be resolved only when persistence first accesses them.
Interview questions
QWhat is the purpose of getStorage in Zustand?
getStorage is a zero-argument function passed to createJSONStorage. It returns a StateStorage implementation, whose required operations are getItem, setItem, and removeItem; createJSONStorage adapts that engine for persistence.
Follow-up: Why use a callback instead of passing the engine directly? The callback lets the helper obtain the engine lazily when storage is first needed, which is useful when the storage API may not exist during initial evaluation.
QWhat is the signature of createJSONStorage?
Its signature is (getStorage: () => StateStorage, options?: JsonStorageOptions) => StateStorage. The first argument supplies the underlying storage engine, while the optional second argument configures JSON-storage behavior.
Follow-up: What must a custom engine provide? It must expose compatible getItem, setItem, and removeItem methods, with the appropriate synchronous or asynchronous behavior for the chosen storage.
QHow is getStorage used with the persist middleware?
A custom storage engine can be wrapped with createJSONStorage(() => customStorage) and then passed as the storage option to persist. This gives persist a storage object suitable for reading and writing serialized state.
Follow-up: How would you adapt IndexedDB? Implement the three storage methods around an IndexedDB wrapper, then return that wrapper from the callback and pass the resulting storage to persist.
Related
createJSONStorageStateStoragepersistPersistStorageJsonStorageOptions