RFC: deprecate equalityFn towards v5 (migration path exists)

[dai-shi]

This can be controversial, but let's go.

Motivation

A part of Zustand philosophy is being small, crazy small. Supporting custom equalityFn requires a bit of code. In v5, the minimal requirement will be React 18, which means we can technically drop use-sync-external-store because we no longer need a shim. Only what's blocking is equalityFn. (Dropping use-sync-external-store is preferable not only for size, but for avoiding bundling issues.)

While the primary recommendation is not specifying equalityFn (which means to use the default Object.is), some users would like to use shallow by default.

Proposal

We deprecate specifying equalityFn in create from zustand. It will be completely removed in v5.

We provide new createWithEqualityFn from zustand/traditional, which supports equalityFn. We can specify shallow as a default equality function.

Migration

If you don't use equalityFn, nothing needs to be done.

If you always use shallow, you no longer need to specify for each hook, but just at creation:

- import { create } from 'zustand'
+ import { createWithEqualityFn } from 'zustand/traditional'
  import { shallow } from 'zustand/shallow'

- const useFooStore = create(...)
+ const useFooStore = createWithEqualityFn(..., shallow)

    // in a component
-   const { ... } = useFooStore(..., shallow)
+   const { ... } = useFooStore(...)

You can use equalityFn other than shallow, or occasionally use custom equality function:

- import { create } from 'zustand'
+ import { createWithEqualityFn } from 'zustand/traditional'

- const useFooStore = create(...)
+ const useFooStore = createWithEqualityFn(..., Object.is) // or deepEqual here

    // in a component
    const { ... } = useFooStore(..., deepEqual)

Benefits

From the library perspective, we can make use-sync-external-store an optional peer dependency, and it's only required when people use shallow or other equality functions.

For users who use shallow always, it gets simpler.

Drawbacks

We have two create functions which can be confusing.

Some people have to migrate, but we are not sure how many people there are. (We assume it's relatively minor.)

For people who use equalityFn other than shallow, it feels weird to import it from zustand/shallow.

Alternatives

We could simply drop equalityFn and let people directly use use-sync-external-store with createStore if they need equalityFn.

---

• Edit 1: Rename to createWithShallow from create.
• Edit 2: Introduce zustand/traditional and make the usage more explicit.

[grumd]

How about this?

import { create, shallow } from 'zustand/equality-fn';
const useStore = create(..., shallow);

Importing "zustand/shallow" to use a custom equality function, and not actually using "shallow" is counter-intuitive, doesn't feel like a good choice.

Or maybe

import { create } from 'zustand/with-equality-fn';
import { shallow } from 'zustand/shallow';

[grumd]

Additionally, "zustand/shallow" could re-export "create" from "zustand/with-equality-fn" and just default the function to "shallow"

[dai-shi]

Importing "zustand/shallow" to use a custom equality function, and not actually using "shallow" is counter-intuitive, doesn't feel like a good choice.

That's totally understandable, and I agree. I'm not sure how many people use custom equality functions. (How many people feel it's counter-intuitive.)

Or maybe

import { create } from 'zustand/with-equality-fn';
import { shallow } from 'zustand/shallow';

Yeah, that's theoretically better. Only the concern is with-equality-fn isn't cute.
Let's find a good name and it should be good to go.

Another issue I just noticed is we should avoid reusing create naming, because it confuses editor to autocomplete.

So:

import { createWithEqualityFn } from 'zustand/with-equality-fn'
import { createWithShallow } from 'zustand/shallow'

Now, with-equality-fn looks good and doesn't need to be so "cute".

[dai-shi]

I'd go with zustand/traditional only.

[dai-shi]

#1945 is open.

[guenyoo]

While I like this change, I'm a bit confused about this being a breaking change. Shouldn't this have been a new major update instead of a minor bump? @dai-shi

[dai-shi]

#1945 only deprecates previous usage (w/ equalityFn) and warns it. You can still use it as the warning is dev only.
When we release v5, we will completely remove the deprecated usage.

[NastykSwED]

Hey guys, what about this pattern?

// Mimic the hook returned by `create`
import { useContext } from 'react'
import { useStore } from 'zustand'

function useBearContext<T>(
  selector: (state: BearState) => T,
  equalityFn?: (left: T, right: T) => boolean
): T {
  const store = useContext(BearContext)
  if (!store) throw new Error('Missing BearContext.Provider in the tree')
  return useStore(store, selector, equalityFn)
}

From: https://docs.pmnd.rs/zustand/guides/initialize-state-with-props

I have this pattern throughout my project and when updating to the latest version of zustand, it tells me that the useStore is deprecated and gives a compilation error, it tells me to import useStoreWithEqualityFn, but when doing the project build, the console tells me this: [DEPRECATED] Use createWithEqualityFn from 'zustand/traditional'. #1937

[dai-shi]

Thanks for the catch! Yeah, docs should be updated too.

Curious why useStoreWithEqualityFn doesn't work for you.

// Mimic the hook returned by `create`
import { useContext } from 'react'
import { useStoreWithEqualityFn } from 'zustand/traditional'

function useBearContext<T>(
  selector: (state: BearState) => T,
  equalityFn?: (left: T, right: T) => boolean
): T {
  const store = useContext(BearContext)
  if (!store) throw new Error('Missing BearContext.Provider in the tree')
  return useStoreWithEqualityFn(store, selector, equalityFn)
}

[dai-shi]

and gives a compilation error,

Reported in another thread, and I noticed a bug.
Please see: #1937 (reply in thread)

[NastykSwED]

Hello mate, I have tried again and now I don't have any warning in the console, thank you.

[maidh91]

We could simply drop equalityFn and let people directly use use-sync-external-store with createStore if they need equalityFn.

hi @dai-shi, can you please give an example how to use use-sync-external-store with createStore to get the same behavior with the previous implementation like this

import { create } from 'zustand';
import { shallow } from 'zustand/shallow';

const store = create(...)
const foo = store(someSelector, shallow);

Thank you ❤️

[dai-shi]

import { createStore } from 'zustand';
import { shallow } from 'zustand/shallow';
import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';

const store = createStore(...);
const foo = useSyncExternalStoreWithSelector(
  store.subscribe,
  store.getState,
  store.getState,
  someSelector,
  shallow
);

[maidh91]

Thank you so much for the lighting response!

Is there any difference in the speed between using your code above and using the traditional lib like this?

import { createWithEqualityFn } from 'zustand/traditional';
import { shallow } from 'zustand/shallow';

const store = createWithEqualityFn(...);
const foo = store(someSelector, shallow);

[dai-shi]

It's basically the same thing.

[puxiao]

If you use TypeScript:

- import { create } from 'zustand'
+ import { createWithEqualityFn } from 'zustand/traditional'

interface UseMyData { ... }

- const useMyData = create<UseMyData>()((set) => ({ ... }))
+ const useMyData = createWithEqualityFn<UseMyData>((set) => ({ ... }), Object.is)

There is no need to make any changes when you use it.

import { shallow } from 'zustand/shallow'

const myData = useMyData((state) => state, shallow)

[maidh91]

Hi @dai-shi, I got this error when using createWithEqualityFn + devtools

the code is like this

const store = createWithEqualityFn<Store>(devtools((set) => {
   ...
}), shallow);

the error is like this

Argument of type 'StateCreator<Store, [], [["zustand/devtools", never]]>' is not assignable to parameter of type 'StateCreator<Store, [], []>'.
  Type 'StateCreator<Store, [], [["zustand/devtools", never]]>' is not assignable to type '{ $$storeMutators?: [] | undefined; }'.
    Types of property '$$storeMutators' are incompatible.
      Type '[["zustand/devtools", never]] | undefined' is not assignable to type '[] | undefined'.
        Type '[["zustand/devtools", never]]' is not assignable to type '[]'.
          Source has 1 element(s) but target allows only 0.ts(2345)
(alias) devtools<Store, [], []>(initializer: StateCreator<Store, [["zustand/devtools", never]], []>, devtoolsOptions?: DevtoolsOptions | undefined): StateCreator<...>
import devtools

[dai-shi]

Please try this:

const store = createWithEqualityFn<Store>()(devtools((set) => {
   ...
}), shallow);

[maidh91]

thank you so much, it works

now I can see why you define the overloaded function in createWithEqualityFn type, so amazing 💯 💯 💯

type CreateWithEqualityFn = {
    <T, Mos extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, [], Mos>, defaultEqualityFn: <U>(a: U, b: U) => boolean): UseBoundStoreWithEqualityFn<Mutate<StoreApi<T>, Mos>>;
    <T>(): <Mos extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, [], Mos>, defaultEqualityFn: <U>(a: U, b: U) => boolean) => UseBoundStoreWithEqualityFn<Mutate<StoreApi<T>, Mos>>;
};

[dai-shi]

Yeah, that's like a magic.
We have a discussion related to it: #1865

[revnelson]

How should we use this when building our store with slices? I tried with the following, but still get the deprecated warning:

Example slice:

import { StateCreator } from "zustand"

export type UISliceType = typeof initialState & {
  ui: {
    setDarkMode: (dark: boolean) => void
    setMobileMenuOpen: (mobileMenuOpen: boolean) => void
    setSearchOpen: (searchOpen: boolean) => void
  }
}

export const initialState = {
  ui: {
    dark: false,
    mobileMenuOpen: false,
    searchOpen: false,
  },
}

const createUISlice: StateCreator<UISliceType, [], []> = (set) => ({
  ui: {
    ...initialState.ui,
    setDarkMode: (dark) => set((state) => ({ ui: { ...state.ui, dark } })),
    setMobileMenuOpen: (mobileMenuOpen) =>
      set((state) => ({ ui: { ...state.ui, mobileMenuOpen } })),
    setSearchOpen: (searchOpen) =>
      set((state) => ({ ui: { ...state.ui, searchOpen } })),
  },
})

export default createUISlice

Example create function:

export const createClientStore = (initialState?: initialStateType) => {
  return createWithEqualityFn<SlicesType>()((...a) => ({
    ...createAlertSlice(...a),
    ...createAuthSlice(initialState?.auth)(...a),
    ...createCartSlice(initialState?.cart)(...a),
    ...createShopSlice(...a),
    ...createUISlice(...a),
  }), shallow)
}

[dai-shi]

Ohhh, that's not intentional! We should fix it.

Would you be able to create a repro with https://www.typescriptlang.org/play ?

[guenyoo]

Sure. Here you go: https://stackblitz.com/edit/vitejs-vite-ejdvk6?file=src%2Fstore.ts,tsconfig.json&terminal=dev

Edit: don't focus on the set obviously. It's the equals part that's erroring for me.

Edit2: Removed the set

[dai-shi]

Thanks, here's the playground version: https://tsplay.dev/WPKoEm

[dai-shi]

@guenyoo Can you try #1972?
https://ci.codesandbox.io/status/pmndrs/zustand/pr/1972
☝️ Find "Local Install Instructions"

[guenyoo]

@dai-shi works for me locally, no longer errors out.

[vijaybritto]

This breaks for context usage like import {createStore, useStore} from 'zustand'. Please provide a replacement API for this createStore API too
If I follow the example mentioned in the migration section in this page https://docs.pmnd.rs/zustand/previous-versions/zustand-v3-create-context it breaks with an error like getSnapshot is not a function

[dai-shi]

Sorry for the confusion. I should have included this in the migration guide.
createStore isn't changed, and what you should do for useStore with equalityFn is this:

- import { createStore, useStore } from 'zustand'
+ import { createStore } from 'zustand'
+ import { useStoreWithEqualityFn as useStore} from 'zustand/traditional'

If I follow the example mentioned in the migration section in this page https://docs.pmnd.rs/zustand/previous-versions/zustand-v3-create-context it breaks with an error like getSnapshot is not a function

Wait, the migration section doesn't use equalityFn. So, I'm confused why such an error can happen. I might be missing something. Would you please create a reproduction with https://codesandbox.io/s/react-new ?

[vijaybritto]

I think the zustand version in codesandbox's NPM registry is not upto date with NPM. The zustand version available there is 4.3.7 while I'm trying in 4.4.0.
The export doesn't seem to be available in that version

But I tried your suggestion and it works

import { useStoreWithEqualityFn } from 'zustand/traditional';
import { shallow } from 'zustand/shallow';

export const useTableStore = (selector) => {
  const context = useContext(TableContext);
  return useStoreWithEqualityFn(context, selector, shallow);
};

[dai-shi]

alright, so you are using the equality function. yes, that's the right solution.

for csb npm version issue, if you edit package.json manually, it would probably work.

[fabrizio-vitale-deltatre]

I've just found this long list of warnings in my console.

Is there an @deprecated or you're just doing a console.warn()?

My 2 cents on the topic

I often use one these patterns in my components:

• useStore(myStore, selector)
• useStore(myStore, selector, shallow)

I really hope that it will still be possible to prevent unnecessary rerenders with useStore(/* [...] */, shallow).

[dai-shi]

It's console.warn, and I knew this could happen because from the library perspective, it can't easily know if it's used throw create or useStore directly. Sorry about that. Let me try to improve the warning message.

In your case, you want to do something like this:

import { useStoreWithEqualityFn as useStore } from 'zustand/traditional'

[dai-shi]

Can you try #1976?
https://ci.codesandbox.io/status/pmndrs/zustand/pr/1976
☝️ Find "Local Install Instructions"

[enricoros]

I never use create with an equality function across all my stores (but often and selectively use shallow comparisons) - and my app outputs this to the console in production.

I'm not sure I'm getting the warning messages because of the v5 transition, rather this seems like a false positive.

[sannajammeh]

Certainly! The biggest problem was the change in API.
Currently without digging through this github RFC I was faced with these questions:

1. How do I use createWithEqualityFn, is it just a drop in for replace?
2. Since its coming from zustand/traditional - is there a new behavior in Zustand which is currently better?
3. Where does the actual equalityFn go now? Is it just applied everywhere?

Lastly, if you're able to put a link inside the code warning to either this RFC or the updated docs it would be great. At least for me it took some time to find it through google, had to go into issues and there it was.

[dai-shi]

Thanks for your feedback.

1. How do I use createWithEqualityFn, is it just a drop in for replace?

It's just a drop-in replacement, but you can't omit equalityFn.
So, the following two are equivalent:

const useFooStore = create(...)
const useFooStore = createWithEqualityFn(..., Object.is)

Object.is is the default equality function.

2. Since its coming from zustand/traditional - is there a new behavior in Zustand which is currently better?

If you don't need equalityFn (= if the default Object.is works fine for your case), you don't need createWithEqualityFn, which will be a bigger bundle than create in v5.

3. Where does the actual equalityFn go now? Is it just applied everywhere?

The function passee to the second argument of createWithEqualityFn is applied everywhere (but not middleware), and it's still customizable for each hook.

Lastly, if you're able to put a link inside the code warning to either this RFC or the updated docs it would be great. At least for me it took some time to find it through google, had to go into issues and there it was.

Hmm, I think I did put the link inside the code warnings.

The biggest problem was the change in API.

Now, I'm a bit confused where those should be documented...

[sannajammeh]

Thanks for the response! Perhaps my React native logs omitted the URL.

The reason I mentioned the change in API was that there was no explanation behind it.

Most use cases for it was applying the shallow function but only selectively, so I was a little confused on how to do that.

[mblarsen]

Thanks for answering @sannajammeh 's questions. Useful little FAQ.

I'm still a bit confused about the future API. Let's assume that I'm on React 18 and v5 of Zustand has been released.

If I need to a custom equality function but only for some uses of the store, I have some questions:

0. Will traditional continue to be a part of the api?
1. How do I create the store?
2. How do I use useStore?

In general I'm not sure where to handle equality and the traditional module/lpackage suggest that is not the way of the future.

[dai-shi]

We don't know the future, but zustand/traditional should stay in v5. That's the reason we split the entry point.
zustand/traditional since v4.4.2- should be identical to the original version, so you can just change the import to migrate.

- import { create } from 'zustand' // -v4.3.9
+ import { createWithEqualityFn as create } from 'zustand/traditional' // v4.4.2-

(If you are using createStore / useStore, the diff is slightly different, but basically the same.)

[markacola]

Hi @dai-shi - First, thank you for all your efforts with this library, it is much appreciated!

Would it be possible to have this warning shown only one time? It is currently logging on every interaction with my app and clogging up my console during dev, making it hard to view other issues or log values to the console.

Screencast.from.06-08-23.00.36.51.webm

Happy to open a PR if this is an accepted suggestion.

[dai-shi]

Can you try #1976?
https://ci.codesandbox.io/status/pmndrs/zustand/pr/1976
☝️ Find "Local Install Instructions"

[markacola]

Hi @dai-shi - apologies for not testing this out sooner and missing the reference to #1976 above. That has fully resolved my issues - thanks!

[arvinxx]

I Just open a issue to track the migration : #1982

[dai-shi]

Let's use this #1937 for discussion.

[arvinxx]

I have migrated most of my codebase to zustand v4.4 ,so close it.

[divmgl]

I'm a bit confused. Part of our workflow is to use Zustand to avoid prop drilling. As a result we create selectors that create arrays, and then we use shallow to do shallow comparisons so that updates are only triggered when the array items change:

const [propA, propB] = useMyStore(state => [state.propA, state.propB], shallow)

We use this pattern everywhere, and it's generally understood why this pattern exists. Why is this changing now in a minor version? Is the v5 version going to do a shallow comparison by default? Having to now change all of our code to use traditional is really cumbersome. If we avoid using traditional, does this now mean that we need to now write this:

const propA = useMyStore(state => state.propA)
const propB = useMyStore(state => state.propB)

This will be the second big change that will require us to rework large portions of our code (the first being the zustand/context deprecation).

[dai-shi]

Sorry for the confusion.
This change is important for the upcoming v5, and we want people to prepare for it in v4. (and get feedback like this.)

it's generally understood why this pattern exists.

Yes, we understand the use case of equalityFn. It's just different implementation-wise.

Is the v5 version going to do a shallow comparison by default?

It's the other way around. v5 will do Object.is comparison by default and it is not configurable. (Like how useState works.)

You need to use zustand/traditional endpoint for shallow.
Using zustand/traditional for shallow is required in v5.
Using zustand/traditional for shallow is technically optional in v4, but I understand the deprecation message is very strong. (but, it's kind of intentional, because otherwise people will only give feedback after v5 is released.)

(the first being the zustand/context deprecation).

I'm sorry about that. I hope this change is far smaller than that one. Basically, all you need in your code base is the following.

- import { create } from 'zustand'
+ import { createWithEqualityFn } from 'zustand/traditional'

- const useMyStore = create(...)
+ const useMyStore = createWithEqualityFn(..., Object.is)

You wouldn't need to change the use of useMyStore then. Does that change your perspective? Hope to get follow-up feedback.

[divmgl]

I appreciate the very quick response. I'm just not understanding the why of this change. Currently the docs are very clear about comparison functions. We'd be losing a lot of API simplicity for not much benefit, given that there would be no way of doing shallow comparisons with v5. Shallow comparisons are basically Zustand's bread and butter in our complex React app, given that we can very deliberately control how rerenders will happen. If that goes away (and the API suffers for it) then we'd either need to stay on v4 permanently (and potentially miss out on new Zustand features) or move away from it to using React.Context with memo everywhere.

And ultimately that's kind of what we're debating right now on our team. I left a message on Discord talking about our use-case and whether Zustand is a good fit for us. We're ultimately using to avoid prop drilling in sets of React components rather than as a global store. https://discord.com/channels/740090768164651008/740093228904218657/1138197849444732950

[dai-shi]

Thanks again for your feedback. Our understanding is that the primary usage of Zustand is the default Object.is comparison and shallow is secondary. The point is we provide a single API for both usages in v4, but in v5, it will be two separate APIs (and the different entry point is important.)

In short, the why of the change is that React is designed with Object.is comparison and using shallow is optional.

given that there would be no way of doing shallow comparisons with v5.

v5 doesn't remove zustand/traditional. Maybe the name is misleading.

We'd be losing a lot of API simplicity for not much benefit

We got some requests for the shallow use cases in the past.
Some of them are that people don't want to specify shallow for each useMyStore call.
createWithEqualityFn is an improvement for it and you can now specify shallow as the default equality function.

So, in summary, I guess there's some miscommunication between us. I think it's really nice that we did this deprecation in v4 and we can discuss on it.

---

or move away from it to using React.Context with memo everywhere.

On a side node, if I were working on a big company project and were to consider the risk of depending on Zustand, I would consider building a custom global state util like Zustand, because it's such a simple util (especially now we can use use-sync-external-store package.)

Some refs:

• https://twitter.com/dai_shi/status/1583082766081531905
• https://egghead.io/courses/create-a-zustand-like-module-state-library-bf55241e

[divmgl]

Super helpful, thank you! So if we didn't want to do shallow comparisons anymore (and we want to avoid rerenders) in v5 the choice would be to not use arrays or objects (since they're created on every render) and when possible use memoization? Obviously, there's the traditional package but we want to make sure we're using Zustand as vanilla as possible.

[dai-shi]

I think you already know it but let me clarify again. It is recommended to use zustand/traditional if you use shallow. Internally, it uses the package from the React team and we should expect it's stable.

The following is unrelated to the change in v4.4.0:
If you want to avoid custom equality function, the first option is to use useMyStore hook multiple times. If that's not enough, useMemo might help too. The second option is to use memoization. You would probably want some third-party libraries such as reselect or proxy-memoize.
The first option can be easier but less efficient depending on the requirements. The second option can be efficient but it's usually hard to do it right. Using shallow can be considered something between the first option and the second option.

[dai-shi]

#1982 (comment)

@arvinxx I think you need useStoreWithEqualityFn.

- export { useStore } from 'zustand';
+ export { useStoreWithEqualityFn as useStore } from 'zustand/traditional';

Thanks for reporting this. I wasn't aware that it affects mocking. Any suggestion to improve docs for others?

[dai-shi]

That's a great finding! Can @dbritto-dev help with mocking??

[arvinxx]

@dai-shi is there any update with this? We can't continue to mirgrate due to this mock problem

[dai-shi]

So I should mock the 'zustand/traditional'. But how can I write this mock ?

I wonder if you try to look for some other resources for a solution. This isn't a Zustand specific issue, I suppose.

[arvinxx]

I have make the test pass with this: #1982 (comment)

[dai-shi]

Thanks for sharing!

[jech33]

Hey @dai-shi love all the work you guys have done with Zustand, it is my go-to library for state management 🧸. I'm dropping by to ask if it is possible to update the docs on how to create a store, some people on my team got confused as their console got the deprecated warning, we are updating our docs as well.

It should be createWithEqualityFn from zustand/traditional right?

Thank you again for this awesome work!

[dai-shi]

Thanks for the feedback. I feel like the deprecation message was kind of too strong (btw, #1976 fixed the repeated warnings.)
It probably takes months before v5 actually lands, so my hope is to get feedback meanwhile and improve the docs.
Let me fix readme.md first and then discuss about docs with contributors @chrisk-7777 @sewera @dbritto-dev and others (we welcome more contributors!)

[dai-shi]

#1985

[jech33]

Thanks for your quick response! Cool, I'll keep an eye on it (and I'd love to contribute in any way I can! hahaha, just let me know)

[cleisonmp]

• What would we miss from v5 by using createWithEqualityFn?

• Would you say the better way to get multiple objects from the store would be like like bellow and avoid using shallow?

  const propA = useMyStore(state => state.propA)
  const propB = useMyStore(state => state.propB)
  

[dai-shi]

We don't miss anything in v5. We generally prefer educating multiple hooks to shallow, but technically shallow can be a little more efficient and some people like the syntax too.

[D-Niermann]

Hi,
I am a bit confused about these warning messages about using createWithEqualityFn from 'zustand/traditional', because I get them a lot in a very simple example (using https://reactflow.dev/docs/examples/overview/).
I am not even importing anything from Zustand or using any other hooks, but when moving a node or similar, these warnings show up in the console.

How can I get rid of all these warnings, not even using Zustand?

Using Versions:

    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1",
    "reactflow": "^11.7.4",
    "typescript": "^4.9.5",
    "web-vitals": "^2.1.4",
    "websocket": "^1.0.34"

Many thanks!

[arvinxx]

using the latest reactflow

[dai-shi]

Maybe look into node_modules and find which package depends on Zustand?

[D-Niermann]

Thanks, updating to newest Version solved the issue.

[fhucko]

This update makes me trust NPM package updates even less. I cannot update this package, if I do not want to spend 30+ minutes of figuring out how to update my code.

[dkouvdis-parloa]

I tried migrating to createWithEqualityFn, devtools and persist are not yet supported.

[dai-shi]

Thanks for reporting. Can you make a reproduction with https://codesandbox.io/s/react-new ?

[strblr]

First of all, thanks for that amazing library. I think this upgrade does the opposite of its intention, it adds complexity. Zustand is appreciated mainly I think because it's dead simple to use in all edge cases. One way to solve every frustrating part of global state management. It's satisfying to not have to think about which special import to use for the store factory based on what one intends to do in the future (shallow comparaison or not, locally or globally). I do not think that the gain in code size justifies this, it just feels wrong and over-engineered. This is of course just my opinion.

I've read the full thread, the argument that it will help people who complained about having to specify "shallow" every time seems weird. One can always create a shared one-line custom hook that wraps useStore and passes shallow. I also doubt that a lot of users would like to use shallow all the time, it would break simple array retrieval from the store based on reference equality.

[dai-shi]

Okay, I think there is a huge misconception between us. AND, I don't mean I know the best practice.
If people say useStore+shallow is the best practice, I don't disagree with it.

My understanding is people using shallow is not the majority, but not minority either.
I wonder how we should document things, but we can take time on it.

To elaborate a bit about the philosophy.
React's useSyncSternalStore doesn't support shallow. Only a separate library use-sync-external-store does. So, the philosophy of React is primarily Object.is comparison. shallow comparison is secondary. Zustand follows the same philosophy.

I guess the practical question is whether "extracting a slice of the state" use case is best with shallow, or there are other (unknown?) practices with Object.is.

[dai-shi]

Here's a naive approach:

  const selectSession = sessionSelectors.getSessionById(id)
  const active = useSessionStore((s) => s.activeId === id);
  const loading = useSessionStore((s) => !!s.chatLoadingId && id === s.activeId);
  const pin = useSessionStore((s) => selectSession(s).pinned);
  const title = useSessionStore((s) => agentSelectors.getTitle(selectSession(s).meta));
  const description = useSessionStore((s) => agentSelectors.getDescription(selectSession(s).meta));
  const avatar = useSessionStore((s) => agentSelectors.getAvatar(selectSession(s).meta));
  const systemRole = useSessionStore((s) => selectSession(s).config.systemRole);
  const avatarBackground = useSessionStore((s) => selectSession(s).meta.backgroundColor);
  const updateAt = useSessionStore((s) => selectSession(s)?.updateAt);
  const model = useSessionStore((s) => selectSession(s).config.model);

[arvinxx]

Here's a naive approach:

Yeah, it's more clear. But it still need 10x useSessionStore and selectSession code,not the same simple with the array one.

[dai-shi]

Trying something different: https://codesandbox.io/s/determined-james-n42tpw?file=/src/App.js
...but, createWithEqualityFn is much cleaner.
Ideally, memoizing selector is an ultimate solution, but might not match with DX.

I think what would be worth exploring is deriving data on update, which might also have a performance benefit. But, that's probably not a solution for you as the mental model is very different.

[dai-shi]

Ideally, memoizing selector is an ultimate solution

Not ideal, but to show the idea. I don't think it's acceptable.

const cache = new Map(); // can leak memory
const useSessionStoreById = (id) => {
  return useSessionStore((s) => {
    const session = sessionSelectors.getSessionById(id)(s);
    const meta = session.meta;
    const systemRole = session.config.systemRole;
    const value = [
      s.activeId === id,
      !!s.chatLoadingId && id === s.activeId,
      session.pinned,
      agentSelectors.getTitle(meta),
      agentSelectors.getDescription(meta),
      systemRole,
      agentSelectors.getAvatar(meta),
      meta.backgroundColor,
      session?.updateAt,
      session.config.model,
    ];
  });
  const prev = cache.get(id);
  if (shallow(prev, value)) {
    return prev;
  }
  cache.set(id, value);
  return value;
};

[timmevandermeer]

I use shallow frequently to create computed / derived state within a hook e.g. here where I only want an render when the keys in an object (Record<string, Properties>) change but not when the values change:

const objects = useObjects((state) => Object.keys(state.objects), shallow);

It surprised me to see this pattern which is prominently part of the documentation be demoted like this. Why is it that shallow comparison is not possible without use-sync-external-store?

[dai-shi]

It's been silent, but I'm leaning to useShallow because the implementation is minimal and readable. Unless we get more feedback, I'll open a PR. (Or, would anyone be interested in working on it? I'm happy to review!)

[fabrizio-vitale-deltatre]

Overall useShallow seems a valid solution.

I can't make promises but I wouldn't mind take a shot a it during this weekend.

Is there an issue?

[dai-shi]

@fabrizio-vitale-deltatre

I can't make promises but I wouldn't mind take a shot a it during this weekend.

We can wait for that for sure. Feel free to ask anything ambiguous here or in the pr. (it's not surprising to have questions because not everything is noted.)

[dai-shi]

#2090 by @FaberVitale

[dai-shi]

follow-up #2097 by @dbritto-dev

[avin-kavish]

Not a fan of tying the equality function to the store. Whether to use shallow is a choice we make based on the selector not something we apply to the entire store.

I also create selectors outside react, so maybe add something like a createShallow utility for that?

[dai-shi]

Not a fan of tying the equality function to the store.

Thanks for the feedback. We changed it since the first proposal and it's now optional. You don't need to pass it to the store.

[Cow258]

is it correct? 👀

zustand-v4

  const [
    isLoaded,
    isLoading,
    posts,
    pagination,
    updateAt,
    fetchNext,
    reset,
  ] = usePageCache(state => {
    const cache = state.caches[cacheKey] || {}
    return [
      cache.isLoaded,
      cache.isLoading,
      cache.posts,
      cache.pagination,
      cache.updateAt,
      state.fetchNext,
      state.reset,
    ]
  }, shallow)

zustand-v5

  const [
    isLoaded,
    isLoading,
    posts,
    pagination,
    updateAt,
    fetchNext,
    reset,
  ] = usePageCache(
    useShallow(
      state => {
        const cache = state.caches[cacheKey] || {}
        return [
          cache.isLoaded,
          cache.isLoading,
          cache.posts,
          cache.pagination,
          cache.updateAt,
          state.fetchNext,
          state.reset,
        ]
      }
    )
  )

[dai-shi]

correct except that you don't need to wait for v5. v4 already has useShallow.

[gsouf]

I'm sorry for my ignorance here, but in the initial message you said :

If you don't use equalityFn, nothing needs to be done.

However, I'm not sure what is the equalityFn, most likely I'm not using but still I get warnings.

Does the following code use equalityFn ?

import { create } from 'zustand';

const useBearStore = create(set => ({
  count: 0,
  addBear: () => set(state => ({
     count: state.count + 1
  })),
}));



function BearCounter() {
        const addBear = useBearStore(state => state.addBear);
        const count = useBearStore(state => state.count);

        return ...
}

Thanks!

[gsouf]

@dai-shi thanks I understand. In that case all of my calls to useBearStore will now use shallow comparison, and there is no way to choose that once it's created right?

Does that mean that in V5 I have to do a compromise and once the store is create I have to always use the same comparison method when I call useBearStore?

In my whole app I'm using shallow only once for a very specific use case. If my understanding is correct, when I will migrate to v5, if I need shallow only in one place, then I need to migrate all other calls to useBearStore to be compatible with the shallow comparison format (ie return an array of items rather than the item I need) ?

[dai-shi]

In that case all of my calls to useBearStore will now use shallow comparison, and there is no way to choose that once it's created right?

No, by default it's object.is comparison, so createWithEqualityFn and create work identically.
(Originally, createWithEqualityFn requires an equality fn, but it's now optional.)

[gsouf]

@dai-shi my question was about how to use the store once it's created. Sorry for not explaining well, here is an example of what I want to migrate:

import { create } from 'zustand';
import { shallow } from 'zustand/shallow';

const useBearStore = create(set => ({
  count: 0,
  addBear: () => set(state => ({
     count: state.count + 1
  })),
}));



function BearCounter() {
        const addBear = useBearStore(state => state.addBear);
        const countAndAddBear = useBearStore(state => [state.count, state.addBear], shallow);

        return ...
}

So I use the same store with two different equality functions, is that still possible in v5 ?

Thanks!

[dai-shi]

Yes, simply do this:

- import { create } from 'zustand';
+ import { createWithEqualityFn as create } from 'zustand/traditional';

[Ahl-am]

thanks a lot, this solved my issue.

[DanielPower]

With React 18, useSyncExternalStore is included in React and does not have to be installed as a separate package. With that in mind, is this change to Zustand still necessary, given that the proposed benefits are bundle size and bundling complexity?

[dai-shi]

Yes, removing equalityFn is necessary to use React 18's useSyncExternalStore.