zustand-middleware
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseZustand - Middleware
Zustand - 中间件
Zustand provides powerful middleware to enhance store functionality including persistence, Redux DevTools integration, immutable updates with Immer, and more.
Zustand 提供强大的中间件来增强状态仓库功能,包括持久化、Redux DevTools 集成、借助 Immer 实现不可变更新等。
Key Concepts
核心概念
Middleware Composition
中间件组合
Middleware wraps the store creator function:
typescript
import { create } from 'zustand'
import { persist, devtools } from 'zustand/middleware'
const useStore = create(
devtools(
persist(
(set) => ({
count: 0,
increment: () => set((state) => ({ count: state.count + 1 })),
}),
{ name: 'counter-storage' }
)
)
)中间件会包装状态仓库创建函数:
typescript
import { create } from 'zustand'
import { persist, devtools } from 'zustand/middleware'
const useStore = create(
devtools(
persist(
(set) => ({
count: 0,
increment: () => set((state) => ({ count: state.count + 1 })),
}),
{ name: 'counter-storage' }
)
)
)Order Matters
顺序至关重要
Apply middleware from inside out:
typescript
// ✅ Correct order
create(devtools(persist(immer(...))))
// devtools wraps persist wraps immer wraps your store从内到外应用中间件:
typescript
// ✅ 正确顺序
create(devtools(persist(immer(...))))
// devtools 包裹 persist,persist 包裹 immer,immer 包裹你的状态仓库Best Practices
最佳实践
1. Persist Middleware
1. Persist 中间件
Save and restore store state to localStorage or other storage:
typescript
import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
interface CartStore {
items: CartItem[]
addItem: (item: CartItem) => void
removeItem: (id: string) => void
clearCart: () => void
}
const useCartStore = create<CartStore>()(
persist(
(set) => ({
items: [],
addItem: (item) =>
set((state) => ({ items: [...state.items, item] })),
removeItem: (id) =>
set((state) => ({
items: state.items.filter((item) => item.id !== id),
})),
clearCart: () => set({ items: [] }),
}),
{
name: 'shopping-cart',
storage: createJSONStorage(() => localStorage),
}
)
)将状态仓库的状态保存并恢复到 localStorage 或其他存储中:
typescript
import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
interface CartStore {
items: CartItem[]
addItem: (item: CartItem) => void
removeItem: (id: string) => void
clearCart: () => void
}
const useCartStore = create<CartStore>()(
persist(
(set) => ({
items: [],
addItem: (item) =>
set((state) => ({ items: [...state.items, item] })),
removeItem: (id) =>
set((state) => ({
items: state.items.filter((item) => item.id !== id),
})),
clearCart: () => set({ items: [] }),
}),
{
name: 'shopping-cart',
storage: createJSONStorage(() => localStorage),
}
)
)Persist Options
Persist 配置项
typescript
persist(
(set) => ({ /* store */ }),
{
name: 'my-store', // unique name for storage key
storage: createJSONStorage(() => localStorage), // or sessionStorage
partialize: (state) => ({ count: state.count }), // only persist specific fields
onRehydrateStorage: (state) => {
console.log('hydration starts')
return (state, error) => {
if (error) {
console.log('error during hydration', error)
} else {
console.log('hydration finished')
}
}
},
version: 1,
migrate: (persistedState, version) => {
// Handle version migrations
if (version === 0) {
// migrate old state to new format
}
return persistedState
},
}
)typescript
persist(
(set) => ({ /* store */ }),
{
name: 'my-store', // 存储键的唯一名称
storage: createJSONStorage(() => localStorage), // 或 sessionStorage
partialize: (state) => ({ count: state.count }), // 仅持久化特定字段
onRehydrateStorage: (state) => {
console.log('hydration starts')
return (state, error) => {
if (error) {
console.log('error during hydration', error)
} else {
console.log('hydration finished')
}
}
},
version: 1,
migrate: (persistedState, version) => {
// 处理版本迁移
if (version === 0) {
// 将旧状态迁移到新格式
}
return persistedState
},
}
)2. DevTools Middleware
2. DevTools 中间件
Integrate with Redux DevTools for debugging:
typescript
import { create } from 'zustand'
import { devtools } from 'zustand/middleware'
interface Store {
count: number
increment: () => void
decrement: () => void
}
const useStore = create<Store>()(
devtools(
(set) => ({
count: 0,
increment: () =>
set((state) => ({ count: state.count + 1 }), false, 'increment'),
decrement: () =>
set((state) => ({ count: state.count - 1 }), false, 'decrement'),
}),
{ name: 'CounterStore' }
)
)与 Redux DevTools 集成以进行调试:
typescript
import { create } from 'zustand'
import { devtools } from 'zustand/middleware'
interface Store {
count: number
increment: () => void
decrement: () => void
}
const useStore = create<Store>()(
devtools(
(set) => ({
count: 0,
increment: () =>
set((state) => ({ count: state.count + 1 }), false, 'increment'),
decrement: () =>
set((state) => ({ count: state.count - 1 }), false, 'decrement'),
}),
{ name: 'CounterStore' }
)
)DevTools Options
DevTools 配置项
typescript
devtools(
(set) => ({ /* store */ }),
{
name: 'MyStore', // name in devtools
enabled: process.env.NODE_ENV === 'development', // enable conditionally
anonymousActionType: 'action', // default action name
trace: true, // include stack traces
}
)typescript
devtools(
(set) => ({ /* store */ }),
{
name: 'MyStore', // DevTools 中的名称
enabled: process.env.NODE_ENV === 'development', // 条件启用
anonymousActionType: 'action', // 默认操作名称
trace: true, // 包含堆栈跟踪
}
)3. Immer Middleware
3. Immer 中间件
Write immutable updates with mutable syntax:
typescript
import { create } from 'zustand'
import { immer } from 'zustand/middleware/immer'
interface TodoStore {
todos: Todo[]
addTodo: (text: string) => void
toggleTodo: (id: string) => void
updateTodo: (id: string, text: string) => void
}
const useTodoStore = create<TodoStore>()(
immer((set) => ({
todos: [],
addTodo: (text) =>
set((state) => {
state.todos.push({
id: Date.now().toString(),
text,
completed: false,
})
}),
toggleTodo: (id) =>
set((state) => {
const todo = state.todos.find((t) => t.id === id)
if (todo) {
todo.completed = !todo.completed
}
}),
updateTodo: (id, text) =>
set((state) => {
const todo = state.todos.find((t) => t.id === id)
if (todo) {
todo.text = text
}
}),
}))
)使用可变语法编写不可变更新:
typescript
import { create } from 'zustand'
import { immer } from 'zustand/middleware/immer'
interface TodoStore {
todos: Todo[]
addTodo: (text: string) => void
toggleTodo: (id: string) => void
updateTodo: (id: string, text: string) => void
}
const useTodoStore = create<TodoStore>()(
immer((set) => ({
todos: [],
addTodo: (text) =>
set((state) => {
state.todos.push({
id: Date.now().toString(),
text,
completed: false,
})
}),
toggleTodo: (id) =>
set((state) => {
const todo = state.todos.find((t) => t.id === id)
if (todo) {
todo.completed = !todo.completed
}
}),
updateTodo: (id, text) =>
set((state) => {
const todo = state.todos.find((t) => t.id === id)
if (todo) {
todo.text = text
}
}),
}))
)4. Subscriptions
4. 订阅
Listen to state changes outside React:
typescript
const useStore = create<Store>()((set) => ({ /* ... */ }))
// Subscribe to all changes
const unsubscribe = useStore.subscribe((state, prevState) => {
console.log('State changed:', state)
})
// Subscribe to specific values
const unsubscribe = useStore.subscribe(
(state) => state.count,
(count, prevCount) => {
console.log('Count changed from', prevCount, 'to', count)
}
)
// Clean up
unsubscribe()在 React 外部监听状态变化:
typescript
const useStore = create<Store>()((set) => ({ /* ... */ }))
// 订阅所有变化
const unsubscribe = useStore.subscribe((state, prevState) => {
console.log('State changed:', state)
})
// 订阅特定值
const unsubscribe = useStore.subscribe(
(state) => state.count,
(count, prevCount) => {
console.log('Count changed from', prevCount, 'to', count)
}
)
// 清理
unsubscribe()5. Combining Multiple Middleware
5. 组合多个中间件
typescript
import { create } from 'zustand'
import { devtools, persist } from 'zustand/middleware'
import { immer } from 'zustand/middleware/immer'
interface Store {
count: number
todos: Todo[]
increment: () => void
addTodo: (text: string) => void
}
const useStore = create<Store>()(
devtools(
persist(
immer((set) => ({
count: 0,
todos: [],
increment: () =>
set((state) => {
state.count++
}),
addTodo: (text) =>
set((state) => {
state.todos.push({
id: Date.now().toString(),
text,
completed: false,
})
}),
})),
{
name: 'app-storage',
partialize: (state) => ({
count: state.count,
todos: state.todos,
}),
}
),
{ name: 'AppStore' }
)
)typescript
import { create } from 'zustand'
import { devtools, persist } from 'zustand/middleware'
import { immer } from 'zustand/middleware/immer'
interface Store {
count: number
todos: Todo[]
increment: () => void
addTodo: (text: string) => void
}
const useStore = create<Store>()(
devtools(
persist(
immer((set) => ({
count: 0,
todos: [],
increment: () =>
set((state) => {
state.count++
}),
addTodo: (text) =>
set((state) => {
state.todos.push({
id: Date.now().toString(),
text,
completed: false,
})
}),
})),
{
name: 'app-storage',
partialize: (state) => ({
count: state.count,
todos: state.todos,
}),
}
),
{ name: 'AppStore' }
)
)Examples
示例
Custom Logging Middleware
自定义日志中间件
typescript
import { StateCreator, StoreMutatorIdentifier } from 'zustand'
type Logger = <
T,
Mps extends [StoreMutatorIdentifier, unknown][] = [],
Mcs extends [StoreMutatorIdentifier, unknown][] = []
>(
f: StateCreator<T, Mps, Mcs>,
name?: string
) => StateCreator<T, Mps, Mcs>
type LoggerImpl = <T>(
f: StateCreator<T, [], []>,
name?: string
) => StateCreator<T, [], []>
const loggerImpl: LoggerImpl = (f, name) => (set, get, store) => {
const loggedSet: typeof set = (...a) => {
set(...a)
console.log(...(name ? [`${name}:`] : []), get())
}
store.setState = loggedSet
return f(loggedSet, get, store)
}
export const logger = loggerImpl as unknown as Logger
// Usage
const useStore = create<Store>()(
logger(
(set) => ({
count: 0,
increment: () => set((state) => ({ count: state.count + 1 })),
}),
'CounterStore'
)
)typescript
import { StateCreator, StoreMutatorIdentifier } from 'zustand'
type Logger = <
T,
Mps extends [StoreMutatorIdentifier, unknown][] = [],
Mcs extends [StoreMutatorIdentifier, unknown][] = []
>(
f: StateCreator<T, Mps, Mcs>,
name?: string
) => StateCreator<T, Mps, Mcs>
type LoggerImpl = <T>(
f: StateCreator<T, [], []>,
name?: string
) => StateCreator<T, [], []>
const loggerImpl: LoggerImpl = (f, name) => (set, get, store) => {
const loggedSet: typeof set = (...a) => {
set(...a)
console.log(...(name ? [`${name}:`] : []), get())
}
store.setState = loggedSet
return f(loggedSet, get, store)
}
export const logger = loggerImpl as unknown as Logger
// 用法
const useStore = create<Store>()(
logger(
(set) => ({
count: 0,
increment: () => set((state) => ({ count: state.count + 1 })),
}),
'CounterStore'
)
)Custom Reset Middleware
自定义重置中间件
typescript
import { StateCreator, StoreMutatorIdentifier } from 'zustand'
type Resettable = <
T,
Mps extends [StoreMutatorIdentifier, unknown][] = [],
Mcs extends [StoreMutatorIdentifier, unknown][] = []
>(
f: StateCreator<T, Mps, Mcs>
) => StateCreator<T, Mps, Mcs>
type ResettableImpl = <T>(
f: StateCreator<T, [], []>
) => StateCreator<T, [], []>
const resettableImpl: ResettableImpl = (f) => (set, get, store) => {
const initialState = f(set, get, store)
store.reset = () => set(initialState)
return initialState
}
export const resettable = resettableImpl as unknown as Resettable
// Extend store type
declare module 'zustand' {
interface StoreApi<T> {
reset?: () => void
}
}
// Usage
const useStore = create<Store>()(
resettable((set) => ({
count: 0,
name: '',
increment: () => set((state) => ({ count: state.count + 1 })),
setName: (name) => set({ name }),
}))
)
// Reset to initial state
useStore.reset()typescript
import { StateCreator, StoreMutatorIdentifier } from 'zustand'
type Resettable = <
T,
Mps extends [StoreMutatorIdentifier, unknown][] = [],
Mcs extends [StoreMutatorIdentifier, unknown][] = []
>(
f: StateCreator<T, Mps, Mcs>
) => StateCreator<T, Mps, Mcs>
type ResettableImpl = <T>(
f: StateCreator<T, [], []>
) => StateCreator<T, [], []>
const resettableImpl: ResettableImpl = (f) => (set, get, store) => {
const initialState = f(set, get, store)
store.reset = () => set(initialState)
return initialState
}
export const resettable = resettableImpl as unknown as Resettable
// 扩展仓库类型
declare module 'zustand' {
interface StoreApi<T> {
reset?: () => void
}
}
// 用法
const useStore = create<Store>()(
resettable((set) => ({
count: 0,
name: '',
increment: () => set((state) => ({ count: state.count + 1 })),
setName: (name) => set({ name }),
}))
)
// 重置为初始状态
useStore.reset()IndexedDB Persistence
IndexedDB 持久化
typescript
import { StateStorage } from 'zustand/middleware'
import { get, set, del } from 'idb-keyval'
const indexedDBStorage: StateStorage = {
getItem: async (name: string): Promise<string | null> => {
return (await get(name)) || null
},
setItem: async (name: string, value: string): Promise<void> => {
await set(name, value)
},
removeItem: async (name: string): Promise<void> => {
await del(name)
},
}
const useStore = create<Store>()(
persist(
(set) => ({
largeData: [],
addData: (data) =>
set((state) => ({ largeData: [...state.largeData, data] })),
}),
{
name: 'large-data-storage',
storage: createJSONStorage(() => indexedDBStorage),
}
)
)typescript
import { StateStorage } from 'zustand/middleware'
import { get, set, del } from 'idb-keyval'
const indexedDBStorage: StateStorage = {
getItem: async (name: string): Promise<string | null> => {
return (await get(name)) || null
},
setItem: async (name: string, value: string): Promise<void> => {
await set(name, value)
},
removeItem: async (name: string): Promise<void> => {
await del(name)
},
}
const useStore = create<Store>()(
persist(
(set) => ({
largeData: [],
addData: (data) =>
set((state) => ({ largeData: [...state.largeData, data] })),
}),
{
name: 'large-data-storage',
storage: createJSONStorage(() => indexedDBStorage),
}
)
)Async Storage for React Native
React Native 异步存储
typescript
import AsyncStorage from '@react-native-async-storage/async-storage'
import { StateStorage } from 'zustand/middleware'
const asyncStorage: StateStorage = {
getItem: async (name: string): Promise<string | null> => {
return await AsyncStorage.getItem(name)
},
setItem: async (name: string, value: string): Promise<void> => {
await AsyncStorage.setItem(name, value)
},
removeItem: async (name: string): Promise<void> => {
await AsyncStorage.removeItem(name)
},
}
const useStore = create<Store>()(
persist(
(set) => ({ /* ... */ }),
{
name: 'app-storage',
storage: createJSONStorage(() => asyncStorage),
}
)
)typescript
import AsyncStorage from '@react-native-async-storage/async-storage'
import { StateStorage } from 'zustand/middleware'
const asyncStorage: StateStorage = {
getItem: async (name: string): Promise<string | null> => {
return await AsyncStorage.getItem(name)
},
setItem: async (name: string, value: string): Promise<void> => {
await AsyncStorage.setItem(name, value)
},
removeItem: async (name: string): Promise<void> => {
await AsyncStorage.removeItem(name)
},
}
const useStore = create<Store>()(
persist(
(set) => ({ /* ... */ }),
{
name: 'app-storage',
storage: createJSONStorage(() => asyncStorage),
}
)
)Common Patterns
常见模式
Conditional Persistence
条件持久化
Only persist certain fields:
typescript
const useStore = create<Store>()(
persist(
(set) => ({
// Persisted
theme: 'light',
language: 'en',
// Not persisted
isLoading: false,
error: null,
setTheme: (theme) => set({ theme }),
setLanguage: (language) => set({ language }),
}),
{
name: 'settings',
partialize: (state) => ({
theme: state.theme,
language: state.language,
}),
}
)
)仅持久化特定字段:
typescript
const useStore = create<Store>()(
persist(
(set) => ({
// 被持久化
theme: 'light',
language: 'en',
// 不被持久化
isLoading: false,
error: null,
setTheme: (theme) => set({ theme }),
setLanguage: (language) => set({ language }),
}),
{
name: 'settings',
partialize: (state) => ({
theme: state.theme,
language: state.language,
}),
}
)
)Version Migration
版本迁移
Handle breaking changes in persisted state:
typescript
const useStore = create<Store>()(
persist(
(set) => ({ /* ... */ }),
{
name: 'app-store',
version: 2,
migrate: (persistedState: any, version: number) => {
if (version === 0) {
// Migrate from version 0 to 1
persistedState.newField = 'default'
}
if (version === 1) {
// Migrate from version 1 to 2
persistedState.items = persistedState.oldItems.map((item: any) => ({
id: item.id,
name: item.title, // renamed field
}))
delete persistedState.oldItems
}
return persistedState as Store
},
}
)
)处理持久化状态中的破坏性变更:
typescript
const useStore = create<Store>()(
persist(
(set) => ({ /* ... */ }),
{
name: 'app-store',
version: 2,
migrate: (persistedState: any, version: number) => {
if (version === 0) {
// 从版本 0 迁移到 1
persistedState.newField = 'default'
}
if (version === 1) {
// 从版本 1 迁移到 2
persistedState.items = persistedState.oldItems.map((item: any) => ({
id: item.id,
name: item.title, // 重命名字段
}))
delete persistedState.oldItems
}
return persistedState as Store
},
}
)
)Hydration Detection
Hydration 检测
Know when persisted state is loaded:
typescript
const useStore = create<Store>()(
persist(
(set) => ({
count: 0,
increment: () => set((state) => ({ count: state.count + 1 })),
}),
{
name: 'counter',
onRehydrateStorage: () => (state) => {
console.log('State hydrated:', state)
},
}
)
)
// In a component
function App() {
const [hydrated, setHydrated] = useState(false)
useEffect(() => {
useStore.persist.onFinishHydration(() => {
setHydrated(true)
})
}, [])
if (!hydrated) {
return <div>Loading...</div>
}
return <div>App content</div>
}了解持久化状态何时加载完成:
typescript
const useStore = create<Store>()(
persist(
(set) => ({
count: 0,
increment: () => set((state) => ({ count: state.count + 1 })),
}),
{
name: 'counter',
onRehydrateStorage: () => (state) => {
console.log('State hydrated:', state)
},
}
)
)
// 在组件中
function App() {
const [hydrated, setHydrated] = useState(false)
useEffect(() => {
useStore.persist.onFinishHydration(() => {
setHydrated(true)
})
}, [])
if (!hydrated) {
return <div>Loading...</div>
}
return <div>App content</div>
}Anti-Patterns
反模式
❌ Don't Persist Sensitive Data
❌ 不要持久化敏感数据
typescript
// Bad: Persisting tokens in localStorage
const useAuthStore = create(
persist(
(set) => ({
token: null,
user: null,
login: async (credentials) => {
const { token, user } = await api.login(credentials)
set({ token, user }) // ❌ Token in localStorage
},
}),
{ name: 'auth' }
)
)
// Good: Use secure storage or don't persist tokens
const useAuthStore = create(
persist(
(set) => ({
user: null,
login: async (credentials) => {
const { token, user } = await api.login(credentials)
secureStorage.setToken(token) // ✅ Secure storage
set({ user })
},
}),
{
name: 'auth',
partialize: (state) => ({ user: state.user }), // ✅ Only persist user
}
)
)typescript
// 错误:在 localStorage 中持久化令牌
const useAuthStore = create(
persist(
(set) => ({
token: null,
user: null,
login: async (credentials) => {
const { token, user } = await api.login(credentials)
set({ token, user }) // ❌ 令牌存储在 localStorage
},
}),
{ name: 'auth' }
)
)
// 正确:使用安全存储或不持久化令牌
const useAuthStore = create(
persist(
(set) => ({
user: null,
login: async (credentials) => {
const { token, user } = await api.login(credentials)
secureStorage.setToken(token) // ✅ 安全存储
set({ user })
},
}),
{
name: 'auth',
partialize: (state) => ({ user: state.user }), // ✅ 仅持久化用户信息
}
)
)❌ Don't Ignore Middleware Order
❌ 不要忽略中间件顺序
typescript
// Bad: DevTools won't see persisted initial state
create(persist(devtools(...)))
// Good: DevTools can see full state lifecycle
create(devtools(persist(...)))typescript
// 错误:DevTools 无法看到持久化的初始状态
create(persist(devtools(...)))
// 正确:DevTools 可以看到完整的状态生命周期
create(devtools(persist(...)))❌ Don't Mutate State Without Immer
❌ 不要在不使用 Immer 的情况下直接修改状态
typescript
// Bad: Mutating without immer
const useStore = create((set) => ({
items: [],
addItem: (item) =>
set((state) => {
state.items.push(item) // ❌ Direct mutation
return state
}),
}))
// Good: Use immer middleware
const useStore = create(
immer((set) => ({
items: [],
addItem: (item) =>
set((state) => {
state.items.push(item) // ✅ Safe with immer
}),
}))
)typescript
// 错误:不使用 Immer 直接修改状态
const useStore = create((set) => ({
items: [],
addItem: (item) =>
set((state) => {
state.items.push(item) // ❌ 直接修改
return state
}),
}))
// 正确:使用 Immer 中间件
const useStore = create(
immer((set) => ({
items: [],
addItem: (item) =>
set((state) => {
state.items.push(item) // ✅ 使用 Immer 安全修改
}),
}))
)❌ Don't Forget to Clean Up Subscriptions
❌ 不要忘记清理订阅
typescript
// Bad: Memory leak
useEffect(() => {
useStore.subscribe((state) => {
console.log(state)
})
}, [])
// Good: Clean up subscription
useEffect(() => {
const unsubscribe = useStore.subscribe((state) => {
console.log(state)
})
return unsubscribe
}, [])typescript
// 错误:内存泄漏
useEffect(() => {
useStore.subscribe((state) => {
console.log(state)
})
}, [])
// 正确:清理订阅
useEffect(() => {
const unsubscribe = useStore.subscribe((state) => {
console.log(state)
})
return unsubscribe
}, [])Related Skills
相关技能
- zustand-store-patterns: Basic store creation and usage
- zustand-typescript: TypeScript integration with middleware
- zustand-advanced-patterns: Custom middleware and advanced techniques
- zustand-store-patterns: 基础状态仓库创建与使用
- zustand-typescript: TypeScript 与中间件集成
- zustand-advanced-patterns: 自定义中间件与高级技巧