Skip to content

Commit 038f496

Browse files
authored
docs(persist): clarify createJSONStorage behavior and warn about production use (#3541)
* docs: expand storage option description in persist.md * docs: warn that createJSONStorage lacks type safety and validation in persist.md * chore: empty commit to retrigger Vercel deploy --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]>
1 parent a1f685c commit 038f496

1 file changed

Lines changed: 18 additions & 2 deletions

File tree

‎docs/reference/middlewares/persist.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,17 @@ persist<T, U = T>(stateCreatorFn: StateCreator<T, [], []>, persistOptions: Persi
5050
Usually, you will return an object with the methods you want to expose.
5151
- `persistOptions`: An object to define storage options.
5252
- `name`: A unique name of the item for your store in the storage.
53-
- **optional** `storage`: Defaults to `createJSONStorage(() => localStorage)`.
53+
- **optional** `storage`: A `PersistStorage` object used to read and write the persisted state.
54+
Defaults to `createJSONStorage(() => localStorage)`. The getter function passed to
55+
`createJSONStorage` is evaluated lazily (only when the storage is first accessed), which
56+
prevents errors in environments where storage APIs like `localStorage` are unavailable at
57+
module evaluation time — for example, during server-side rendering (SSR).
58+
> **Warning:** `createJSONStorage` relies on `JSON.parse` and `JSON.stringify` and does not
59+
> perform any runtime validation. The value read from storage is cast directly to your state
60+
> type without checking its shape, so corrupt, stale, or tampered data will not be caught at
61+
> runtime. For production use, implement a custom `PersistStorage` that validates the
62+
> deserialized value — for example with a schema validation library such as
63+
> [Zod](https://zod.dev).
5464
- **optional** `partialize`: A function to filter state fields before persisting it.
5565
- **optional** `onRehydrateStorage`: A function or function returning a function that allows
5666
custom logic before and after state rehydration.
@@ -337,7 +347,13 @@ Here's the `html` code
337347

338348
### Persisting a state with custom storage
339349

340-
In this mini tutorial, we’ll create a simple position-tracking system using vanilla store, where
350+
> **Note:** `createJSONStorage` is a convenience helper suited for quick prototyping. It uses
351+
> `JSON.parse`/`JSON.stringify` without runtime validation, so unexpected or corrupted data in
352+
> storage is not caught. For production applications, implement a custom `PersistStorage` that
353+
> validates the persisted value, for example using a schema validation library like
354+
> [Zod](https://zod.dev).
355+
356+
In this mini tutorial, we'll create a simple position-tracking system using vanilla store, where
341357
the position state is persisted in the URL's search parameters. This approach allows state
342358
persistence directly in the browser's URL, which can be useful for maintaining state across page
343359
reloads or sharing links with state embedded.

0 commit comments

Comments
 (0)