State Management

Introduction

The Auction Platform uses Zustand for state management. Zustand provides a lightweight, hook-based API for managing global state without the complexity of traditional state management libraries.

Why Zustand?

Simple API

Minimal boilerplate with a straightforward, hook-based interface

No Providers

No context providers needed - stores work out of the box

Type-Safe

Full TypeScript support with excellent type inference

Performant

Fine-grained subscriptions prevent unnecessary re-renders

Store Organization

Stores are located in src/app/store/ and organized by domain:

app/store/
└── auth/
    └── auth.store.ts

Each store follows a consistent structure with state and actions.

Auth Store Example

The auth store manages authentication state and user session:

import { create } from "zustand";
import type { AuthState, User } from "../../../features/auth/types/auth.types";
import { apiGET } from "../../api/client";

type AuthStore = AuthState & {
  init: () => Promise<void>;
  login: (user: User) => void;
  logout: () => void;
}

export const useAuthStore = create<AuthStore>((set, get) => ({
  // Initial State
  isAuthenticated: false,
  isOnboarded: false,
  user: null,
  initialized: false,

  // Actions
  init: async () => {
    if (get().initialized) return;

    try {
      const user: User = await apiGET("/auth/me");
      set({
        user,
        isAuthenticated: true,
        isOnboarded: user.is_onboarded,
        initialized: true,
      });
    } catch {
      set({
        user: null,
        isAuthenticated: false,
        isOnboarded: false,
        initialized: true,
      });
    }
  },

  login: (user) =>
    set({
      user,
      isAuthenticated: true,
      isOnboarded: user.is_onboarded,
      initialized: true,
    }),

  logout: () =>
    set({
      user: null,
      isAuthenticated: false,
      isOnboarded: false,
      initialized: true,
    }),
}));

Store Structure

Each Zustand store follows this pattern:

Define Types

Create TypeScript types for state and the complete store interface.

Initial State

Define the initial state values in the store creator function.

Actions

Add action methods that modify state using set() and read state using get().

Export Hook

Export the store as a custom hook (e.g., useAuthStore).

Using Stores in Components

import { useAuthStore } from '@app/store/auth/auth.store';

function UserProfile() {
  const authStore = useAuthStore();
  
  if (!authStore.isAuthenticated) {
    return <div>Please log in</div>;
  }
  
  return <div>Welcome, {authStore.user?.name}</div>;
}

Subscribing to the entire store causes re-renders on any state change. Use selectors for better performance.

import { useAuthStore } from '@app/store/auth/auth.store';

function UserProfile() {
  // Only re-renders when user changes
  const user = useAuthStore(state => state.user);
  const isAuthenticated = useAuthStore(state => state.isAuthenticated);
  
  if (!isAuthenticated) {
    return <div>Please log in</div>;
  }
  
  return <div>Welcome, {user?.name}</div>;
}

Using selectors ensures components only re-render when the specific state they depend on changes.

Access Store Outside React

Stores can be accessed outside React components:

import { useAuthStore } from '@app/store/auth/auth.store';

// Get current state
const state = useAuthStore.getState();

// Call actions
useAuthStore.getState().logout();

// Subscribe to changes
const unsubscribe = useAuthStore.subscribe(
  state => console.log('State changed:', state)
);

This pattern is used in:

API client for authentication checks (src/app/api/client.ts:28)
Route guards in TanStack Router
Application initialization (src/main.tsx:17)

State Initialization

The auth store is initialized before the application renders:

async function bootstrap() {
  // Initialize auth state from server
  await useAuthStore.getState().init()

  const router = createRouter({ routeTree })

  createRoot(document.getElementById('root')!).render(
    <StrictMode>
      <ErrorBoundary>
        <ThemeProvider>
          <RouterProvider router={router} />
        </ThemeProvider>
      </ErrorBoundary>
    </StrictMode>,
  )
}

bootstrap();

The init() action fetches the current user session from the server, ensuring auth state is ready before routing begins.

Common Patterns

Async Actions

Stores can contain async actions that fetch data and update state:

export const useDataStore = create<DataStore>((set, get) => ({
  data: null,
  loading: false,
  error: null,

  fetchData: async () => {
    set({ loading: true, error: null });
    
    try {
      const data = await apiGET('/data');
      set({ data, loading: false });
    } catch (error) {
      set({ 
        error: error.message, 
        loading: false 
      });
    }
  },
}));

Computed Values

Derive computed values from state:

export const useCartStore = create<CartStore>((set, get) => ({
  items: [],
  
  addItem: (item) => set(state => ({
    items: [...state.items, item]
  })),
  
  // Computed getter
  getTotal: () => {
    return get().items.reduce((sum, item) => sum + item.price, 0);
  },
}));

Immer for Complex Updates

For complex nested state updates, use the immer middleware:

import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

export const useComplexStore = create(
  immer<ComplexStore>((set) => ({
    nested: {
      deep: {
        value: 0
      }
    },
    
    updateDeep: (newValue) => set((state) => {
      // Mutate draft state directly with immer
      state.nested.deep.value = newValue;
    }),
  }))
);

Store Actions vs Services

Store Actions
Feature Services

Use for:

Simple state updates
State transformations
Synchronous operations
Cross-feature state coordination

logout: () => set({ user: null, isAuthenticated: false })

Use for:

API calls
Complex business logic
Feature-specific operations
Data transformations

// src/features/auth/services/auth.service.ts
export async function loginUser(credentials) {
  const response = await apiPOST('/auth/login', {
    body: JSON.stringify(credentials)
  });
  return response;
}

DevTools Integration

Zustand integrates with Redux DevTools for debugging:

import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

export const useAuthStore = create(
  devtools<AuthStore>(
    (set, get) => ({
      // ... store definition
    }),
    { name: 'AuthStore' }
  )
);

Install the Redux DevTools Extension to inspect state changes, time-travel debug, and track actions.

Best Practices

Use Selectors

Always use selectors to subscribe to specific state slices and prevent unnecessary re-renders.

Keep Stores Focused

Create separate stores for different domains (auth, cart, settings) rather than one large store.

Colocate Actions

Define actions in the same store file to keep related logic together.

Type Everything

Use TypeScript for full type safety on state and actions.

Async in Actions

Handle async operations in store actions, but consider moving complex logic to services.

Performance Optimization

Shallow Equality

For selecting multiple values, use shallow equality:

import { shallow } from 'zustand/shallow';

function Component() {
  const { user, isAuthenticated } = useAuthStore(
    state => ({ 
      user: state.user, 
      isAuthenticated: state.isAuthenticated 
    }),
    shallow
  );
}

Transient Updates

For high-frequency updates that don’t need to trigger re-renders:

const updatePosition = useStore.getState().updatePosition;

// Updates state without triggering subscribers
useStore.setState({ x: 100, y: 200 }, true);

Architecture Overview

Learn about the overall architecture

API Client

Understand how stores interact with the API

Routing

See how stores are used in route guards

Zustand Docs

Official Zustand documentation

Get Started

Components

Features

Architecture

Development

Introduction

Why Zustand?

Simple API

No Providers

Type-Safe

Performant

Store Organization

Auth Store Example

Store Structure

Using Stores in Components

Access Store Outside React

State Initialization

Common Patterns

Async Actions

Computed Values

Immer for Complex Updates

Store Actions vs Services

DevTools Integration

Best Practices

Performance Optimization

Shallow Equality

Transient Updates

Architecture Overview

API Client

Routing

Zustand Docs

Build docs developers (and LLMs) love

Get Started

Components

Features

Architecture

Development

​Introduction

​Why Zustand?

Simple API

No Providers

Type-Safe

Performant

​Store Organization

​Auth Store Example

​Store Structure

​Using Stores in Components

​Subscribe to Entire Store

​Subscribe to Specific State (Recommended)

​Access Store Outside React

​State Initialization

​Common Patterns

​Async Actions

​Computed Values

​Immer for Complex Updates

​Store Actions vs Services

​DevTools Integration

​Best Practices

​Performance Optimization

​Shallow Equality

​Transient Updates

​Related Resources

Architecture Overview

API Client

Routing

Zustand Docs

Build docs developers (and LLMs) love

Introduction

Why Zustand?

Store Organization

Auth Store Example

Store Structure

Using Stores in Components

Subscribe to Entire Store

Subscribe to Specific State (Recommended)

Access Store Outside React

State Initialization

Common Patterns

Async Actions

Computed Values

Immer for Complex Updates

Store Actions vs Services

DevTools Integration

Best Practices

Performance Optimization

Shallow Equality

Transient Updates

Related Resources