v5

.eslintrc.json

@@ -45,11 +45,7 @@
     "@typescript-eslint/explicit-module-boundary-types": "off",
     "@typescript-eslint/no-unused-vars": [
       "warn",
-      {
-        "argsIgnorePattern": "^_",
-        "varsIgnorePattern": "^_",
-        "caughtErrorsIgnorePattern": "^_"
-      }
+      { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }
     ],
     "@typescript-eslint/no-use-before-define": "off",
     "@typescript-eslint/no-empty-function": "off",

.github/workflows/test-multiple-builds.yml

@@ -12,8 +12,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        build: [cjs, esm, umd]
-        env: [development, production]
+        build: [cjs, esm]
+        env: [development] # [development, production]
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
@@ -24,10 +24,6 @@ jobs:
           cache-dependency-path: '**/pnpm-lock.yaml'
       - run: pnpm install --frozen-lockfile
       - run: pnpm build
-      - name: Use React 17 for production test
-        if: ${{ matrix.env == 'production' }}
-        run: |
-          pnpm add -D react@17.0.2 react-dom@17.0.2 @testing-library/react@12.1.4
       - name: Patch for DEV-ONLY
         if: ${{ matrix.env == 'development' }}
         run: |
@@ -42,26 +38,13 @@ jobs:
         if: ${{ matrix.build == 'cjs' }}
         run: |
           sed -i~ "s/resolve('\.\/src\(.*\)\.ts')/resolve('\.\/dist\1.js')/" vitest.config.ts
-          sed -i~ "s/module.exports.createStore = vanilla.createStore;//" dist/index.js
       - name: Patch for ESM
         if: ${{ matrix.build == 'esm' }}
         run: |
           sed -i~ "s/resolve('\.\/src\(.*\)\.ts')/resolve('\.\/dist\/esm\1.mjs')/" vitest.config.ts
           sed -i~ "1s/^/import.meta.env=import.meta.env||{};import.meta.env.MODE='${NODE_ENV}';/" tests/*.tsx
         env:
           NODE_ENV: ${{ matrix.env }}
-      - name: Patch for UMD
-        if: ${{ matrix.build == 'umd' }}
-        run: |
-          sed -i~ "s/resolve('\.\/src\(.*\)\.ts')/resolve('\.\/dist\/umd\1.${NODE_ENV}.js')/" vitest.config.ts
-        env:
-          NODE_ENV: ${{ matrix.env }}
-      - name: Patch for SystemJS
-        if: ${{ matrix.build == 'system' }}
-        run: |
-          sed -i~ "s/resolve('\.\/src\(.*\)\.ts')/resolve('\.\/dist\/system\1.${NODE_ENV}.js')/" vitest.config.ts
-        env:
-          NODE_ENV: ${{ matrix.env }}
       - name: Test ${{ matrix.build }} ${{ matrix.env }}
         run: |
           pnpm test:spec

.github/workflows/test-multiple-versions.yml

@@ -27,31 +27,13 @@ jobs:
       fail-fast: false
       matrix:
         react:
-          - 16.8.0
-          - 17.0.0
           - 18.0.0
           - 18.1.0
           - 18.2.0
           - 18.3.1
           - 19.0.0-rc.0
           - 19.0.0-rc-49496d49-20240814
           - 0.0.0-experimental-49496d49-20240814
-        devtools-skip:
-          - CI-MATRIX-NOSKIP
-        include:
-          - devtools-skip: CI-MATRIX-[2345]
-            react: 16.8.0
-          - devtools-skip: CI-MATRIX-[1345]
-            react: 16.8.0
-          - devtools-skip: CI-MATRIX-[1245]
-            react: 16.8.0
-          - devtools-skip: CI-MATRIX-[1235]
-            react: 16.8.0
-          - devtools-skip: CI-MATRIX-[1234]
-            react: 16.8.0
-        exclude:
-          - devtools-skip: CI-MATRIX-NOSKIP
-            react: 16.8.0
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
@@ -61,18 +43,6 @@ jobs:
           cache: 'pnpm'
           cache-dependency-path: '**/pnpm-lock.yaml'
       - run: pnpm install --frozen-lockfile
-      - name: Install legacy testing-library
-        if: ${{ startsWith(matrix.react, '16.') || startsWith(matrix.react, '17.') }}
-        run: pnpm add -D @testing-library/react@12.1.4
-      - name: Patch for React 16
-        if: ${{ startsWith(matrix.react, '16.') }}
-        run: |
-          sed -i~ '1s/^/import React from "react";/' tests/*.tsx
-          sed -i~ 's/"jsx": "react-jsx"/"jsx": "react"/' tsconfig.json
-          sed -i~ 's/import\.meta\.env[?]\.MODE/"DEVELOPMENT".toLowerCase()/' src/*.ts src/*/*.ts
-          sed -i~ "s/it('\[${DEVTOOLS_SKIP}\]/it.skip('/" tests/devtools.test.tsx
-        env:
-          DEVTOOLS_SKIP: ${{ matrix.devtools-skip }}
       - name: Test ${{ matrix.react }} ${{ matrix.devtools-skip }}
         run: |
           pnpm add -D react@${{ matrix.react }} react-dom@${{ matrix.react }}

.github/workflows/test-old-typescript.yml

@@ -23,10 +23,6 @@ jobs:
           - 4.7.4
           - 4.6.4
           - 4.5.5
-          - 4.4.4
-          - 4.3.5
-          - 4.2.3
-          - 4.1.5
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
@@ -43,9 +39,6 @@ jobs:
           sed -i~ 's/"verbatimModuleSyntax": true,//' tsconfig.json
       - name: Patch for Old TS
         run: |
-          sed -i~ 's/\/\/ @ts-expect-error.*\[LATEST-TS-ONLY\]//' tests/*.tsx
-          sed -i~ 's/"target":/"skipLibCheck":true,"target":/' tsconfig.json
-          sed -i~ 's/"exactOptionalPropertyTypes": true,//' tsconfig.json
           sed -i~ 's/"moduleResolution": "bundler",/"moduleResolution": "node",/' tsconfig.json
           sed -i~ 's/"allowImportingTsExtensions": true,//' tsconfig.json
           sed -i~ 's/"zustand": \["\.\/src\/index\.ts"\],/"zustand": [".\/dist\/index.d.ts"],/' tsconfig.json
@@ -55,9 +48,5 @@ jobs:
           pnpm add -D @types/node@18.13.0
       - name: Install old TypeScript
         run: pnpm add -D typescript@${{ matrix.typescript }}
-      - name: Patch testing setup for Old TS
-        if: ${{ matrix.typescript == '4.4.4' || matrix.typescript == '4.3.5' || matrix.typescript == '4.2.3' || matrix.typescript == '4.1.5' }}
-        run: |
-          pnpm add -D vitest@0.33.0 @vitest/coverage-v8@0.33.0 @vitest/ui@0.33.0
       - name: Test ${{ matrix.typescript }}
         run: pnpm test:types

docs/guides/typescript.md

@@ -232,6 +232,36 @@ For a usual statically typed language, this is impossible. But thanks to TypeScr
 
 If you are eager to know what the answer is to this particular problem then you can [see it here](#middleware-that-changes-the-store-type).
 
+### Handling Dynamic `replace` Flag
+
+If the value of the `replace` flag is not known at compile time and is determined dynamically, you might face issues. To handle this, you can use a workaround by annotating the `replace` parameter with `as any`:
+
+```ts
+const replaceFlag = Math.random() > 0.5
+store.setState(partialOrFull, replaceFlag as any)
+```
+
+#### Example with `as any` Workaround
+
+```ts
+import { create } from 'zustand'
+
+interface BearState {
+  bears: number
+  increase: (by: number) => void
+}
+
+const useBearStore = create<BearState>()((set) => ({
+  bears: 0,
+  increase: (by) => set((state) => ({ bears: state.bears + by })),
+}))
+
+const replaceFlag = Math.random() > 0.5
+useBearStore.setState({ bears: 5 }, replaceFlag as any) // Using the workaround
+```
+
+By following this approach, you can ensure that your code handles dynamic `replace` flags without encountering type issues.
+
 ## Common recipes
 
 ### Middleware that doesn't change the store type

docs/migrations/migrating-to-v5.md

@@ -0,0 +1,171 @@
+---
+title: 'How to Migrate to v5 from v4'
+nav: 30
+---
+
+# How to Migrate to v5 from v4
+
+We highly recommend to update to the latest version of v4, before migrating to v5. It will show all deprecation warnings without breaking your app.
+
+## Changes in v5
+
+- Drop default exports
+- Drop deprecated features
+- Make React 18 the minimum required version
+- Make use-sync-external-store a peer dependency (required for `createWithEqualityFn` and `useStoreWithEqualityFn` in `zustand/traditional`)
+- Make TypeScript 4.5 the minimum required version
+- Drop UMD/SystemJS support
+- Organize entry points in the package.json
+- Drop ES5 support
+- Stricter types when setState's replace flag is set
+- Other small improvements (technically breaking changes)
+
+## Migration Guide
+
+### Using custom equality functions such as `shallow`
+
+The `create` function in v5 does not support customizing equality function.
+
+If you use custom equality function such as `shallow`,
+the easiest migration is to use `createWithEqualityFn`.
+
+```js
+// v4
+import { create } from 'zustand'
+import { shallow } from 'zustand/shallow'
+
+const useCountStore = create((set) => ({
+  count: 0,
+  text: 'hello',
+  // ...
+}))
+
+const Component = () => {
+  const { count, text } = useCountStore(
+    (state) => ({
+      count: state.count,
+      text: state.text,
+    }),
+    shallow,
+  )
+  // ...
+}
+```
+
+That can be done with `createWithEqualityFn` in v5:
+
+```bash
+npm install use-sync-external-store
+```
+
+```js
+// v5
+import { createWithEqualityFn as create } from 'zustand/traditional'
+
+// The rest is the same as v4
+```
+
+Alternatively, for the `shallow` use case, you can use `useShallow` hook:
+
+```js
+// v5
+import { create } from 'zustand'
+import { useShallow } from 'zustand/shallow'
+
+const useCountStore = create((set) => ({
+  count: 0,
+  text: 'hello',
+  // ...
+}))
+
+const Component = () => {
+  const { count, text } = useCountStore(
+    useShallow((state) => ({
+      count: state.count,
+      text: state.text,
+    })),
+  )
+  // ...
+}
+```
+
+### Requiring stable selector outputs
+
+There is a behavioral change in v5 to match React default behavior.
+If a selector returns a new reference, it may cause infinite loops.
+
+For example, this may cause infinite loops.
+
+```js
+// v4
+const action = useMainStore((state) => {
+  return state.action ?? () => {}
+})
+```
+
+The error message will be something like this:
+
+```
+Uncaught Error: Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate. React limits the number of nested updates to prevent infinite loops.
+```
+
+To fix it, make sure the selector function returns a stable reference.
+
+```js
+// v5
+
+const FALLBACK_ACTION = () => {}
+
+const action = useMainStore((state) => {
+  return state.action ?? FALLBACK_ACTION
+})
+```
+
+Alternatively, if you need v4 behavior, `createWithEqualityFn` will do.
+
+```js
+// v5
+import { createWithEqualityFn as create } from 'zustand/traditional'
+```
+
+### Stricter types when setState's replace flag is set (Typescript only)
+
+```diff
+- setState:
+-   (partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: boolean | undefined) => void;
++ setState:
++   (partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: false) => void;
++   (state: T | ((state: T) => T), replace: true) => void;
+```
+
+If you are not using the `replace` flag, no migration is required.
+
+If you are using the `replace` flag and it's set to `true`, you must provide a complete state object.
+This change ensures that `store.setState({}, true)` (which results in an invalid state) is no longer considered valid.
+
+**Examples:**
+
+```ts
+// Partial state update (valid)
+store.setState({ key: 'value' })
+
+// Complete state replacement (valid)
+store.setState({ key: 'value' }, true)
+
+// Incomplete state replacement (invalid)
+store.setState({}, true) // Error
+```
+
+#### Handling Dynamic `replace` Flag
+
+If the value of the `replace` flag is dynamic and determined at runtime, you might face issues. To handle this, you can use a workaround by annotating the `replace` parameter with `as any`:
+
+```ts
+const replaceFlag = Math.random() > 0.5
+store.setState(partialOrFull, replaceFlag as any)
+```
+
+## Links
+
+- https://github.com/pmndrs/zustand/pull/2138
+- https://github.com/pmndrs/zustand/pull/2580