Blog Posts

Introducing HPKV's Multiplayer Middleware for Zustand: Build Real-Time Collaborative Apps in Minutes

•5 min read•By Ehsan Aslani

Zustand Multiplayer Middleware

Building real-time collaborative features traditionally requires WebSocket servers, complex synchronization logic, conflict resolution strategies, and persistent state management. What if you could build powerful realtime and collaborative web applications without dealing with any of those complexities?

Zustand has become one of the most popular state management libraries for React, loved by developers for its simplicity, minimal boilerplate, and powerful features. Now, the multiplayer middleware takes Zustand to the next level by bringing real-time synchronization capabilities to your stores without sacrificing that signature simplicity.

Today, we're excited to announce the release of @hpkv/zustand-multiplayer - a powerful middleware that transforms any Zustand store into a real-time synchronized multiplayer experience, powered by HPKV's bi-directional websocket infrastructure.

The Problem: Real-Time Collaboration is not Easy!

Every developer who's tried to build collaborative features knows the pain. You start with a simple requirement - "users should see each other's changes in real-time" - and suddenly you're:

  • Setting up WebSocket servers and managing connections
  • Implementing complex state synchronization protocols
  • Handling network failures and reconnection logic
  • Resolving conflicts when multiple users edit simultaneously
  • Persisting state across sessions
  • Scaling your infrastructure as users grow

The complexity multiplies quickly, turning what should be a product feature into an infrastructure project.

The Solution: Wrap your Zustand Stores with Multiplayer Middleware

HPKV's multiplayer middleware for Zustand eliminates this complexity entirely. Transform any existing Zustand store into a real-time multiplayer experience with just one wrapper:

// Before: Your existing local Zustand store
const useStore = create((set) => ({
  todos: {},
  addTodo: (text) => set(state => ({
    todos: {
      ...state.todos,
      [Date.now()]: { text, completed: false }
    }
  })),
  toggleTodo: (id) => set(state => ({
    todos: {
      ...state.todos,
      [id]: { ...state.todos[id], completed: !state.todos[id].completed }
    }
  }))
}));

// After: Real-time multiplayer with ONE line change!
import { multiplayer } from '@hpkv/zustand-multiplayer';

const useStore = create(
  multiplayer((set) => ({
    todos: {},
    addTodo: (text) => set(state => ({
      todos: {
        ...state.todos,
        [Date.now()]: { text, completed: false }
      }
    })),
    toggleTodo: (id) => set(state => ({
      todos: {
        ...state.todos,
        [id]: { ...state.todos[id], completed: !state.todos[id].completed }
      }
    }))
  }), { 
    namespace: 'my-app-todos',  // Unique namespace for your app
    tokenGenerationUrl: '/api/generate-token'     // your API endpoint for token generation
  })
);

That's it. Your store now syncs in real-time across all connected clients. No WebSocket server setup, no synchronization code, no conflict resolution logic. It just works.

How It Works: The Architecture

Zustand Multiplayer leverages HPKV's WebSocket API to provide instant synchronization without requiring any server infrastructure. Here's what happens under the hood:

  1. State Changes: When any client updates the store, the middleware intercepts the change
  2. Atomic Operations: Changes are persisted to HPKV's distributed database using atomic operations to handle concurrent updates
  3. WebSocket Broadcasting: Updates are instantly pushed to all connected clients via their websocket connections to HPKV
  4. Automatic Reconciliation: Each client receives and applies the changes, keeping everyone in sync

The beauty is in the simplicity - you write your Zustand store exactly as you normally would, and the middleware handles all the complexity.

Features

  • Realtime Multiplayer Zustand Stores: Wrap your Zustand stores with multiplayer middleware and state changes will be synchronized among all connected clients in near real-time.
  • Automatic Persistence: State is automatically persisted on HPKV's database without any coding or configuration.
  • Performance: The state is stored and synchronized with sub-microsecond latency.
  • Selective Sync: Configure which parts of state sync globally vs. stay local
  • Configurable Storage Granularity: Fine-tune how granular the state should be stored to avoid conflicts in concurrent state updates and optimize performance.
  • Framework Agnostic: While it shines with React, it works anywhere Zustand works - vanilla JavaScript, Node.js servers. You can also build server and client stores on the same namespace and synchronize state between client and server.
  • Connection Management: Automatic connection management, reconnection and throttling.
  • Composability: Combine seamlessly with other Zustand middlewares like persist, devtools, or immer
  • Typescript Ready

See It In Action: Collaborative Notes Board

notes board demo

We've built a fully-featured demo application to showcase the power of Zustand Multiplayer. Visit notesboard.hpkv.io to experience real-time collaboration firsthand.

The Notes Board demonstrates:

  • Instant Synchronization: Create a note and watch it appear on other screens immediately
  • Live Presence: See other users' cursors moving in real-time
  • Drag & Drop: Move notes around and see changes reflected everywhere

View the source code of this demo to see how we built this collaborative app.

Start Building Today

Whether you're adding real-time features to an existing app or starting fresh, you can have multiplayer working in literally minutes.

  • Read the Developer Guide to get started
  • See our Real-world Examples to get ideas for building collaborative editors, whiteboard, chat applications and multiplayer games.

Ready to Transform Your App?

Quick Links:

Building something cool with Zustand Multiplayer? We'd love to feature it! Tag us @hpkvHQ on X or submit your project to our show and tell discussion.