💁 zustand-ards

A library of simple opinionated utilities for zustand. zustand-ards are typesafe and designed to be easily added to an existing codebase to improve the experience of developing with zustand.

⚒️ Setup

Install

pnpm i zustand-ards
# or
npm i zustand-ards

Basic Usage

import { withArraySelector } from 'zustand-ards';

const useWithZustandards = withZustandards(useStore);

const { bears, increaseBears } = useWithZustandards(['bears', 'increaseBears']);

🪝 Store Hook Enhancements

import { create } from 'zustand';

interface ExampleStoreState {
  bears: number;
  wizards: number;
  increaseBears: (by: number) => void;
  increaseWizards: (by: number) => void;
}

const useExampleStore = create<ExampleStoreState>()((set) => ({
  bears: 0,
  wizards: 0,
  increaseBears: (by) => set((state) => ({ bears: state.bears + by })),
  increaseWizards: (by) => set((state) => ({ wizards: state.wizards + by })),
}));

💁 withZustandards

This is the recommended zustand-ards setup. It combines withArraySelector and withDefaultShallow.

📝 withArraySelector

This enhances the store hook by adding another style of selector: an array of keys from the provided store. It elimnates the need to use multiple hooks or a complex selector function.

import { withArraySelector } from 'zustand-ards';

const useStoreWithArray = withArraySelector(useExampleStore);

const { bears, increaseBears } = useStoreWithArray(['bears', 'increaseBears']);

The array selector is automatically typed so your IDE should provide hints with all the possible keys.

The original selector functionality still works so you can use the hook with either style of selector.

🏊 withDefaultShallow

This enhances the store hook so access to the provided store is shallow by default. It is effectively the same as passing shallow from zustand/shallow to the original hook every time.

import { withDefaultShallow } from 'zustand-ards';

const useShallowStore = withDefaultShallow(useExampleStore);

const { wizards } = useShallowStore((state) => ({ wizards: state.wizards }));

In the example the changes to the state of bears will have no impact since the hook is only being used to access the state of wizards.

You can always override the shallow option by passing in a custom equality function like so:

const { wizards } = useShallowStore(
  (state) => ({ wizards: state.wizards }),
  (a, b) => a === b
);

Contributing

Feel free to submit PRs or Issues if you find any bugs or have ideas for new zustand-ards. Please keep in mind the goal of this project is to create simple standalone enhancements for zustand that improve the developer experience.

Legal

Copyright © Ivo Ilić 2023

zustand-ards is MIT licensed.

zustand-ards is in no way officially associated with or endorsed by Poimandres or zustand.