docs(persist): add info about createJSONStorage helpful function (#2299)

* first pass at docs

* add jump-to-section
This commit is contained in:
Charles Kornoelje 2024-01-19 21:17:05 -08:00 committed by GitHub
parent 13830c1134
commit 27bffb1fba
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -56,8 +56,7 @@ import { StateStorage } from 'zustand/middleware'
> Default: `createJSONStorage(() => localStorage)`
Enables you to use your own storage.
Simply pass a function that returns the storage you want to use.
Enables you to use your own storage. Simply pass a function that returns the storage you want to use. It's recommended to use the [`createJSONStorage`](#createjsonstorage) helper function to create a `storage` object that is compliant with the `StateStorage` interface.
Example:
@ -415,6 +414,37 @@ const unsub = useBoundStore.persist.onFinishHydration((state) => {
unsub()
```
### `createJSONStorage`
> Type: `(getStorage: () => StateStorage, options?: JsonStorageOptions) => StateStorage`
> Returns: `PersistStorage`
This helper function enables you to create a [`storage`](#storage) object which is useful when you want to use a custom storage engine.
`getStorage` is a function that returns the storage engine with the properties `getItem`, `setItem`, and `removeItem`.
`options` is an optional object that can be used to customize the serialization and deserialization of the data. `options.reviver` is a function that is passed to `JSON.parse` to deserialize the data. `options.replacer` is a function that is passed to `JSON.stringify` to serialize the data.
```ts
import { createJSONStorage } from 'zustand/middleware'
const storage = createJSONStorage(() => sessionStorage, {
reviver: (key, value) => {
if (value && value.type === 'date') {
return new Date(value)
}
return value
},
replacer: (key, value) => {
if (value instanceof Date) {
return { type: 'date', value: value.toISOString() }
}
return value
},
})
```
## Hydration and asynchronous storages
To explain what is the "cost" of asynchronous storages,