Configuration
storage
Configure custom storage adapters for cart persistence.
Type
interface StorageAdapter {
getItem(key: string): Promise<string | null> | string | null
setItem(key: string, value: string): Promise<void> | void
removeItem(key: string): Promise<void> | void
}StorageAdapter is exported from use-shopping-cart and use-shopping-cart/core. Each method can return its result directly or as a Promise.
Default
createLocalStorage() - Uses browser's localStorage
Usage
Default (LocalStorage)
<CartProvider
currency="USD"
// Uses localStorage by default
>
<App />
</CartProvider>SessionStorage
import { createSessionStorage } from 'use-shopping-cart/core'
export const Root = () => (
<CartProvider currency="USD" storage={createSessionStorage()}>
<App />
</CartProvider>
)Memory Storage
import { createMemoryStorage } from 'use-shopping-cart/core'
export const Root = () => (
<CartProvider currency="USD" storage={createMemoryStorage()}>
<App />
</CartProvider>
)No Storage
export const Root = () => (
<CartProvider currency="USD" shouldPersist={false}>
<App />
</CartProvider>
)Built-in Adapters
createLocalStorage() (Default)
import { createLocalStorage } from 'use-shopping-cart/core'
<CartProvider storage={createLocalStorage()}>
<App />
</CartProvider>- Persists across browser sessions
- ~5-10MB storage limit
- Synchronous API
- Used by default if no storage specified
createSessionStorage()
import { createSessionStorage } from 'use-shopping-cart/core'
<CartProvider storage={createSessionStorage()}>
<App />
</CartProvider>- Clears when the tab closes
- ~5-10MB storage limit
- Synchronous API
- Per-tab storage
- Good for temporary shopping sessions
Custom Storage Adapter
Example: Async Storage (React Native)
import AsyncStorage from '@react-native-async-storage/async-storage'
const asyncStorageAdapter = {
getItem: (key) => {
return AsyncStorage.getItem(key)
},
setItem: (key, value) => {
return AsyncStorage.setItem(key, value)
},
removeItem: (key) => {
return AsyncStorage.removeItem(key)
}
}
<CartProvider storage={asyncStorageAdapter}>
<App />
</CartProvider>Example: Server Sync
const serverSyncStorage = {
getItem(key) {
// Return from localStorage as fallback
return localStorage.getItem(key)
},
setItem(key, value) {
// Save locally first
localStorage.setItem(key, value)
// Then sync to server (fire and forget)
fetch('/api/save-cart', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ key, value })
}).catch(console.error)
},
removeItem(key) {
localStorage.removeItem(key)
fetch('/api/clear-cart', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ key })
}).catch(console.error)
}
}
<CartProvider storage={serverSyncStorage} />Example: Compressed Storage
import LZString from 'lz-string'
const compressedStorage = {
getItem(key) {
const compressed = localStorage.getItem(key)
return compressed ? LZString.decompress(compressed) : null
},
setItem(key, value) {
const compressed = LZString.compress(value)
localStorage.setItem(key, compressed)
},
removeItem(key) {
localStorage.removeItem(key)
}
}
<CartProvider storage={compressedStorage} />Example: IndexedDB
import { openDB } from 'idb'
const dbPromise = openDB('cart-db', 1, {
upgrade(db) {
db.createObjectStore('cart')
}
})
const indexedDBStorage = {
async getItem(key) {
const db = await dbPromise
return db.get('cart', key)
},
async setItem(key, value) {
const db = await dbPromise
return db.put('cart', value, key)
},
async removeItem(key) {
const db = await dbPromise
return db.delete('cart', key)
}
}
<CartProvider storage={indexedDBStorage} />Notes
setItemis called when the cart entries, currency or language change, once for changes made together in the same task. With an async adapter, changes made while the saved cart loads are written once the load finishes- Must implement all three methods:
getItem,setItem,removeItem - Methods can be async (return Promises)
- Values are always strings (serialized JSON)
- Handle errors gracefully to prevent cart crashes
- SSR is handled automatically (no special storage needed)
See Also
- Persistence - How persistence works
- shouldPersist - Enable/disable
- persistKey - Storage key
