Zustand is a small, fast and scalable state-management solution battle-tested against common pitfalls, like the dreaded zombie child problem, react concurrency, and context loss between mixed renderers. It may be the one state-manager in the React space that gets all of these right.
As zustand is un-opinionated by design, it's challenging to find out the best patterns to use when creating stores, often leading to boilerplate code.
Zustood, built on top of zustand, is providing a powerful store factory which solves these challenges, so you can focus on your app.
yarn add zustand @udecode/zustood
Visit zustood.netlify.app for the API.
- Much less boilerplate
- Modular state management:
- Derived selectors
- Derived actions
immer
,devtools
andpersist
middlewares- Full typescript support
react-tracked
support
import { createStore } from '@udecode/zustood'
const repoStore = createStore('repo')({
name: 'zustood',
stars: 0,
owner: {
name: 'someone',
email: 'someone@xxx.com',
},
})
- the parameter of the first function is the name of the store, this is helpful when you have multiple stores
- the parameter of the second function is the initial state of your store
- the main difference with zustand is that you don't need to define a getter and a setter for each field, these are generated by zustood
Note that the zustand store is accessible through:
// hook store
repoStore.useStore
// vanilla store
repoStore.store
Use the hooks in React components, no providers needed. Select your
state and the component will re-render on changes. Use the use
method:
repoStore.use.name()
repoStore.use.stars()
We recommend using the global hooks (see below) to support ESLint hook linting.
Big thanks for react-tracked
Use the tracked hooks in React components, no providers needed. Select your
state and the component will trigger re-renders only if the accessed property is changed. Use the useTracked
method:
repoStore.useTracked.owner()
Don't overuse hooks. If you don't need to subscribe to the state, use
instead the get
method:
repoStore.get.name()
repoStore.get.stars()
You can also get the whole state:
repoStore.get.state()
You generally want to write derived selectors (those depending on other selectors) for reusability. Zustood supports extending selectors with full typescript support:
const repoStore = createStore('repo')({
name: 'zustood ',
stars: 0,
middlewares: ['immer', 'devtools', 'persist']
})
.extendSelectors((state, get, api) => ({
validName: () => get.name().trim(),
// other selectors
}))
.extendSelectors((state, get, api) => ({
// get.validName is accessible
title: (prefix: string) =>
`${prefix + get.validName()} with ${get.stars()} stars`,
}))
// extend again...
Update your store from anywhere by using the set
method:
repoStore.set.name('new name')
repoStore.set.stars(repoStore.get.stars + 1)
You can update the whole state from your app:
store.set.state((draft) => {
draft.name = 'test';
draft.stars = 1;
});
However, you generally want to create derived actions for reusability. Zustood supports extending actions with full typescript support:
const repoStore = createStore('repo')({
name: 'zustood',
stars: 0,
})
.extendActions((set, get, api) => ({
validName: (name: string) => {
set.name(name.trim());
},
// other actions
}))
.extendActions((set, get, api) => ({
reset: (name: string) => {
// set.validName is accessible
set.validName(name);
set.stars(0);
},
}))
// extend again...
After having created many stores, it can be difficult to remember which one to import. By combining all the stores, selectors and actions, just pick what you need using TS autocomplete.
import { mapValuesKey } from '@udecode/zustood';
// Global store
export const rootStore = {
auth: authStore,
combobox: comboboxStore,
contextMenu: contextMenuStore,
editor: editorStore,
modal: modalStore,
repo: repoStore,
toolbar: toolbarStore,
};
// Global hook selectors
export const useStore = () => mapValuesKey('use', rootStore);
// Global tracked hook selectors
export const useTrackedStore = () => mapValuesKey('useTracked', rootStore);
// Global getter selectors
export const store = mapValuesKey('get', rootStore);
// Global actions
export const actions = mapValuesKey('set', rootStore);
import shallow from 'zustand/shallow'
useStore().repo.name()
useStore().modal.isOpen()
// prevent unnecessary re-renders
// more see: https://docs.pmnd.rs/zustand/recipes#selecting-multiple-state-slices
useStore().repo.middlewares(shallow)
// with useTrackStore UserEmail Component will only re-render when accessed property owner.email changed
const UserEmail = () => {
const owner = useTrackedStore().repo.owner()
return (
<div>
<span>User Email: {owner.email}</span>
</div>
);
};
// with useStore UserEmail Component re-render when owner changed, but you can pass equalityFn to avoid it.
const UserEmail = () => {
const owner = useStore().repo.owner()
// const owner = useStore().repo.owner((prev, next) => prev.email === next.email)
return (
<div>
<span>User Email: {owner.email}</span>
</div>
);
};
By using useStore() or useTrackStore()
, ESLint will correctly lint hook errors.
store.repo.name()
store.modal.isOpen()
These can be used anywhere.
actions.repo.stars(store.repo.stars + 1)
actions.modal.open()
These can be used anywhere.
The second parameter of createStore
is for options:
export interface CreateStoreOptions<T extends State> {
middlewares?: any[];
devtools?: DevtoolsOptions;
immer?: ImmerOptions;
persist?: PersistOptions;
}
Zustood is using these middlewares:
immer
: required. Autofreeze can be enabled usingimmer.enabledAutoFreeze
option.devtools
: enabled ifdevtools.enabled
option istrue
.persist
: enabled ifpersist.enabled
option istrue
.persist
implementsPersistOptions
interface from zustand- custom middlewares can be added using
middlewares
option
Discussions is the best place for bringing opinions and contributions. Letting us know if we're going in the right or wrong direction is great feedback and will be much appreciated!
🌟 Stars and 📥 Pull requests are welcome! Don't hesitate to share your feedback here. Read our contributing guide to get started.