Migrating to v4#

The only breaking changes are in types. If you are using Zustand with TypeScript or JSDoc type annotations, this guide applies. Otherwise, no migration is required.

Also, it's recommended to first read the new TypeScript Guide, so that the migration is easier to understand.

In addition to this migration guide, you can also check the diff of the test files in the Zustand repository from v3 to v4.

#create

Applicable imports

import create from 'zustand'
import create from 'zustand/vanilla'

Change

- create:
-   < State
-   , StoreSetState = StoreApi<State>["set"]
-   , StoreGetState = StoreApi<State>["get"]
-   , Store = StoreApi<State>
-   >
-     (f: ...) => ...
+ create:
+   { <State>(): (f: ...) => ...
+   , <State, Mutators>(f: ...) => ...
+   }

Migration

If you are not passing any type parameters to create, no migration is required.

If you are using a "leaf" middleware like combine or redux, remove all type parameters from create.

Else, replace create<T, ...>(...) with create<T>()(...).

#StateCreator

Applicable imports

import type { StateCreator } from 'zustand'
import type { StateCreator } from 'zustand/vanilla'

Change

- type StateCreator
-   < State
-   , StoreSetState = StoreApi<State>["set"]
-   , StoreGetState = StoreApi<State>["get"]
-   , Store = StoreApi<State>
-   > =
-     ...
+ type StateCreator
+   < State
+   , InMutators extends [StoreMutatorIdentifier, unknown][] = []
+   , OutMutators extends [StoreMutatorIdentifier, unknown][] = []
+   , Return = State
+   > =
+     ...

Migration

If you are using StateCreator, you are likely authoring a middleware or using the "slices" pattern. For that check the Authoring middlewares and advanced usage and Common recipes sections of the TypeScript Guide.

#PartialState

Applicable imports

import type { PartialState } from 'zustand'
import type { PartialState } from 'zustand/vanilla'

Change

- type PartialState
-   < T extends State
-   , K1 extends keyof T = keyof T
-   , K2 extends keyof T = K1
-   , K3 extends keyof T = K2
-   , K4 extends keyof T = K3
-   > =
-   | (Pick<T, K1> | Pick<T, K2> | Pick<T, K3> | Pick<T, K4> | T)
-   | ((state: T) => Pick<T, K1> | Pick<T, K2> | Pick<T, K3> | Pick<T, K4> | T)
+ type PartialState<T> =
+   | Partial<T>
+   | ((state: T) => Partial<T>)

Migration

Replace PartialState<T, ...> with PartialState<T> and preferably turn on exactOptionalPropertyTypes in your tsconfig.json:

{
  "compilerOptions": {
    "exactOptionalPropertyTypes": true
  }
}

We're no longer using the trick to disallow { foo: undefined } to be assigned to Partial<{ foo: string }>. Instead, we're relying on the users to turn on exactOptionalPropertyTypes.

#useStore

Applicable imports

import { useStore } from 'zustand'
import { useStore } from 'zustand/react'

Change

- useStore:
-   { <State>(store: StoreApi<State>): State
-   , <State, StateSlice>
-       ( store: StoreApi<State>
-       , selector: StateSelector<State, StateSlice>,
-       , equals?: EqualityChecker<StateSlice>
-       ): StateSlice
-   }
+ useStore:
+   <Store, StateSlice = ExtractState<Store>>
+     ( store: Store
+     , selector?: StateSelector<State, StateSlice>,
+     , equals?: EqualityChecker<StateSlice>
+     )
+       => StateSlice

Migration

If you are not passing any type parameters to useStore, no migration is required.

If you are, it's recommended to remove all the type parameters, or pass the store type instead of the state type as the first parameter.

#UseBoundStore

Applicable imports

import type { UseBoundStore } from 'zustand'
import type { UseBoundStore } from 'zustand/react'

Change

- type UseBoundStore<
-   State,
-   Store = StoreApi<State>
- > =
-   & { (): T
-     , <StateSlice>
-         ( selector: StateSelector<State, StateSlice>
-         , equals?: EqualityChecker<StateSlice>
-         ): U
-     }
-   & Store
+ type UseBoundStore<Store> =
+   & (<StateSlice = ExtractState<S>>
+       ( selector?: (state: ExtractState<S>) => StateSlice
+       , equals?: (a: StateSlice, b: StateSlice) => boolean
+       ) => StateSlice
+     )
+   & S

Migration

Replace UseBoundStore<T> with UseBoundStore<StoreApi<T>>, and UseBoundStore<T, S> with UseBoundStore<S>

#UseContextStore

Applicable imports

import type { UseContextStore } from 'zustand/context'

Change

- type UseContextStore

Migration

Use typeof MyContext.useStore instead

#createContext

Applicable imports

import createContext from 'zustand/context'

Change

  createContext:
-   <State, Store = StoreApi<State>>() => ...
+   <Store>() => ...

Migration

Replace createContext<T>() with createContext<StoreApi<T>>(), and createContext<T, S>() with createContext<S>().

#combine, devtools, subscribeWithSelector

Applicable imports

import { combine } from 'zustand/middleware'
import { devtools } from 'zustand/middleware'
import { subscribeWithSelector } from 'zustand/middleware'

Change

- combine:
-   <T, U>(...) => ...
+ combine:
+   <T, U, Mps, Mcs>(...) => ...

- devtools:
-   <T>(...) => ...
+ devtools:
+   <T, Mps, Mcs>(...) => ...

- subscribeWithSelector:
-   <T>(...) => ...
+ subscribeWithSelector:
+   <T, Mps, Mcs>(...) => ...

Migration

If you are not passing any type parameters to combine, devtools, or subscribeWithSelector, no migration is required.

If you are, remove all the type parameters, as they are inferred automatically.

#persist

Applicable imports

import { persist } from 'zustand/middleware'

Change

- persist:
-   <T, U = Partial<T>>(...) => ...
+ persist:
+   <T, Mps, Mcs, U = T>(...) => ...

Migration

If you are passing any type parameters, remove them as they are inferred automatically.

Next, if you are passing the partialize option, there is no further steps required for migration.

If you are not passing the partialize option, you might see some compilation errors. If you do not see any, there is no further migration required.

The type of partialized state is now T instead of Partial<T>, which aligns with the runtime behavior of the default partialize, which is an identity (s => s).

If you see some compilation errors, you have to find and fix the errors yourself, because they might be indicative of unsound code. Alternatively, the workaround will be passing s => s as Partial<typeof s> to partialize. If your partialized state is truly Partial<T>, you should not encounter any bugs.

The runtime behavior has not changed, only the types are now correct.

#redux

Applicable imports

import { redux } from 'zustand/middleware'

Change

- redux:
-   <T, A>(...) => ...
+ redux:
+   <T, A, Mps, Mcs>(...) => ...

Migration

If you are not passing any type parameters to redux, no migration is required.

If you are, remove all the type parameters, and annotate only the second (action) parameter. That is, replace redux<T, A>((state, action) => ..., ...) with redux((state, action: A) => ..., ...).