npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2025 – Pkg Stats / Ryan Hefner

zustand-x

v6.1.0

Published

Zustand store factory for a best-in-class developer experience.

Downloads

427,576

Readme

Zustand X

An extension for Zustand that auto-generates type-safe actions, selectors, and hooks for your state. Built with TypeScript and React in mind.

Features

  • Auto-generated type-safe hooks for each state field
  • Simple patterns: store.get('name') and store.set('name', value)
  • Extend your store with computed values using extendSelectors
  • Add reusable actions with extendActions
  • Built-in support for devtools, persist, immer, and mutative

Why

Built on top of zustand, zustand-x offers a better developer experience with less boilerplate. Create and interact with stores faster using a more intuitive API.

Looking for React Context-based state management instead of global state? Check out Jotai X - same API, different state model.

Installation

pnpm add zustand-x

You'll also need react and zustand installed.

Quick Start

Here's how to create a simple store:

import { createStore, useStoreState, useStoreValue } from 'zustand-x';

// Create a store with an initial state
const repoStore = createStore({
  name: 'ZustandX',
  stars: 0,
});

// Use it in your components
function RepoInfo() {
  const name = useStoreValue(repoStore, 'name');
  const stars = useStoreValue(repoStore, 'stars');

  return (
    <div>
      <h1>{name}</h1>
      <p>{stars} stars</p>
    </div>
  );
}

function AddStarButton() {
  const [, setStars] = useStoreState(repoStore, 'stars');
  return <button onClick={() => setStars((s) => s + 1)}>Add star</button>;
}

Core Concepts

Store Configuration

The store is where everything begins. Configure it with type-safe middleware:

import { createStore } from 'zustand-x';

// Types are inferred, including middleware options
const userStore = createStore(
  {
    name: 'Alice',
    loggedIn: false,
  },
  {
    name: 'user',
    devtools: true, // Enable Redux DevTools
    persist: true, // Persist to localStorage
    mutative: true, // Enable immer-style mutations
  }
);

Available middleware options:

{
  name: string;
  devtools?: boolean | DevToolsOptions;
  persist?: boolean | PersistOptions;
  immer?: boolean | ImmerOptions;
  mutative?: boolean | MutativeOptions;
}

Reading and Writing State

The API is designed to be intuitive. Here's how you work with state:

Reading State

// Get a single value
store.get('name'); // => 'Alice'

// Get the entire state
store.get('state');

// Call a selector with arguments
store.get('someSelector', 1, 2);

Writing State

// Set a single value
store.set('name', 'Bob');

// Call an action
store.set('someAction', 10);

// Update multiple values at once
store.set('state', (draft) => {
  draft.name = 'Bob';
  draft.loggedIn = true;
});

Subscribing State

// Subscribe to changes
const unsubscribe = store.subscribe('name', (name, previousName) => {
  console.log('Name changed from', previousName, 'to', name);
});

// Subscribe to the entire state
const unsubscribe = store.subscribe('state', (state) => {
  console.log('State changed:', state);
});

// Subscribe to a selector with arguments
const unsubscribe = store.subscribe('someSelector', 1, 2, (result) => {
  console.log('Selector result changed:', result);
});

// Subscribe with an additional selector and options
const unsubscribe = store.subscribe(
  'name',
  name => name.length,
  length => console.log('Name length changed:', length),
  { fireImmediately: true } // Fire the callback immediately when subscribing
);

React Hooks

useStoreValue(store, key, ...args)

Subscribe to a single value or selector. Optionally pass an equality function for custom comparison:

const name = useStoreValue(store, 'name');

// With selector arguments
const greeting = useStoreValue(store, 'greeting', 'Hello');

// With custom equality function for arrays/objects
const items = useStoreValue(
  store,
  'items',
  (a, b) => a.length === b.length && a.every((item, i) => item.id === b[i].id)
);

useStoreState(store, key, [equalityFn])

Get a value and its setter, just like useState. Perfect for form inputs:

function UserForm() {
  const [name, setName] = useStoreState(store, 'name');
  const [email, setEmail] = useStoreState(store, 'email');

  return (
    <form>
      <input value={name} onChange={(e) => setName(e.target.value)} />
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
    </form>
  );
}

useTracked(store, key)

Subscribe to a value with minimal re-renders. Perfect for large objects where you only use a few fields:

function UserEmail() {
  // Only re-renders when user.email changes
  const user = useTracked(store, 'user');
  return <div>{user.email}</div>;
}

function UserAvatar() {
  // Only re-renders when user.avatar changes
  const user = useTracked(store, 'user');
  return <img src={user.avatar} />;
}

useTrackedStore(store)

Get the entire store with tracking.

function UserProfile() {
  // Only re-renders when accessed fields change
  const state = useTrackedStore(store);

  return (
    <div>
      <h1>{state.user.name}</h1>
      <p>{state.user.bio}</p>
      {state.isAdmin && <AdminPanel />}
    </div>
  );
}

Extending Your Store

Adding Selectors

Selectors help you derive new values from your state. Chain them together to build complex computations:

const store = createStore(
  { firstName: 'Jane', lastName: 'Doe' },
  { mutative: true }
);

const extendedStore = store
  .extendSelectors(({ get }) => ({
    fullName: () => get('firstName') + ' ' + get('lastName'),
  }))
  .extendSelectors(({ get }) => ({
    fancyTitle: (prefix: string) => prefix + get('fullName').toUpperCase(),
  }));

// Using them
extendedStore.get('fullName'); // => 'Jane Doe'
extendedStore.get('fancyTitle', 'Hello '); // => 'Hello JANE DOE'

Use them in components:

function Title() {
  const fancyTitle = useStoreValue(extendedStore, 'fancyTitle', 'Welcome ')
  return <h1>{fancyTitle}</h1>
}

Adding Actions

Actions are functions that modify state. They can read or write state and even compose with other actions:

const storeWithActions = store.extendActions(
  ({ get, set, actions: { someActionToOverride } }) => ({
    updateName: (newName: string) => set('name', newName),
    resetState: () => {
      set('state', (draft) => {
        draft.firstName = 'Jane';
        draft.lastName = 'Doe';
      });
    },
    someActionToOverride: () => {
      // You could call the original if you want:
      // someActionToOverride()
      // then do more stuff...
    },
  })
);

// Using actions
storeWithActions.set('updateName', 'Julia');
storeWithActions.set('resetState');

Middleware Configuration

Each middleware can be enabled with a simple boolean or configured with options:

const store = createStore(
  { name: 'ZustandX', stars: 10 },
  {
    name: 'repo',
    devtools: { enabled: true }, // Redux DevTools with options
    persist: { enabled: true }, // localStorage with options
    mutative: true, // shorthand for { enabled: true }
  }
);

Zustand Store

Access the underlying Zustand store when needed:

// Use the original Zustand hook
const name = useStoreSelect(store, (state) => state.name);

// Get the vanilla store
const vanillaStore = store.store;
vanillaStore.getState();
vanillaStore.setState({ count: 1 });

// Subscribe to changes
const unsubscribe = vanillaStore.subscribe((state) =>
  console.log('New state:', state)
);

Comparison with Zustand

// zustand
import create from 'zustand'

const useStore = create((set, get) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  // Computed values need manual memoization
  double: 0,
  setDouble: () => set((state) => ({ double: state.count * 2 }))
}))

// Component
const count = useStore((state) => state.count)
const increment = useStore((state) => state.increment)
const double = useStore((state) => state.double)

// zustand-x
import { createStore, useStoreValue, useStoreState } from 'zustand-x'

const store = createStore({ count: 0 })
  .extendSelectors(({ get }) => ({
    // Computed values are auto-memoized
    double: () => get('count') * 2
  }))
  .extendActions(({ set }) => ({
    increment: () => set('count', (count) => count + 1),
  }))

// Component
const count = useStoreValue(store, 'count')
const double = useStoreValue(store, 'double')
const increment = () => store.set('increment')

Key differences:

  • No need to create selectors manually - they're auto-generated for each state field
  • Direct access to state fields without selector functions
  • Simpler action definitions with set('key', value) pattern
  • Type-safe by default without extra type annotations
  • Computed values are easier to define and auto-memoized with extendSelectors

Migration to v6

// Before
store.use.name();
store.get.name();
store.set.name('Bob');

// Now
useStoreValue(store, 'name');
store.get('name');
store.set('name', 'Bob');

// With selectors and actions
// Before
store.use.someSelector(42);
store.set.someAction(10);

// Now
useStoreValue(store, 'someSelector', 42);
store.set('someAction', 10);

License

MIT