@zocket/react

Type-safe React hooks for Zocket WebSockets. Build real-time applications with end-to-end type safety.

Installation

bun add @zocket/react @zocket/core zod

Quick Start

1. Define your router (server-side)

import { z } from "zod";
import { zocket } from "@zocket/core";

const zo = zocket.create();

const appRouter = {
  posts: {
    create: zo.message.incoming({
      payload: z.object({ title: z.string() }),
    }),
    created: zo.message.outgoing({
      payload: z.object({
        id: z.string(),
        title: z.string(),
      }),
    }),
  },
  users: {
    joined: zo.message.outgoing({
      payload: z.object({ name: z.string() }),
    }),
  },
};

export type AppRouter = typeof appRouter;

2. Wrap your app with ZocketProvider

import { ZocketProvider } from "@zocket/react";
import type { AppRouter } from "./server";

function App() {
  return (
    <ZocketProvider<AppRouter>
      url="ws://localhost:3000"
      onOpen={() => console.log("Connected!")}
      onClose={() => console.log("Disconnected")}
    >
      <YourApp />
    </ZocketProvider>
  );
}

3. Use type-safe hooks in any component

import { useZocket } from "@zocket/react";
import type { AppRouter } from "./server";

function ChatComponent() {
  const { client, useEvent } = useZocket<AppRouter>();
  const [messages, setMessages] = useState([]);

  useEvent(client.on.posts.created, (data) => {
    setMessages((prev) => [...prev, data]);
  });

  useEvent(client.on.users.joined, (data) => {
    console.log(`${data.name} joined!`);
  });

  const sendMessage = () => {
    client.send.posts.create({ title: "Hello!" });
  };

  return (
    <div>
      <button onClick={sendMessage}>Send</button>
      {messages.map((msg) => (
        <div key={msg.id}>{msg.title}</div>
      ))}
    </div>
  );
}

API Reference

<ZocketProvider>

Provider component that creates and manages a WebSocket connection.

Props:

• url: string - WebSocket URL to connect to
• children: ReactNode - React children
• maxReconnectionDelay?: number - Max delay between reconnection attempts (default: 10000ms)
• minReconnectionDelay?: number - Min delay between reconnection attempts (default: 1000ms)
• reconnectionDelayGrowFactor?: number - Growth factor for reconnection delay (default: 1.3)
• maxRetries?: number - Maximum reconnection attempts (default: Infinity)
• debug?: boolean - Enable debug logging (default: false)
• headers?: Record<string, string> - Custom headers for connection
• onOpen?: () => void - Callback when connection opens
• onClose?: () => void - Callback when connection closes

useZocket<TRouter>()

Hook to access the Zocket client and event listener.

Returns:

• client: ZocketClient<TRouter> - The Zocket client instance for sending messages
• useEvent: (event, handler) => void - Hook for type-safe event listening

useEvent(subscribeFn, handler)

Type-safe event listener hook (returned from useZocket).

Parameters:

• subscribeFn: (callback) => UnsubscribeFn - Subscription function from client.on (e.g., client.on.posts.created)
• handler: (payload) => void - Event handler (payload is fully typed and automatically inferred)

Features:

• Automatically subscribes on mount
• Automatically unsubscribes on unmount
• Full TypeScript inference for event payloads based on router definition
• Compile-time type safety - catches invalid event names and incorrect payload types

Features

• Type Safety - End-to-end type safety from server to client
• Auto Reconnection - Built-in reconnection with exponential backoff
• Auto Cleanup - Event listeners are automatically cleaned up
• React Idiomatic - Follows React patterns and best practices
• Zero Config - Works out of the box with sensible defaults

License

MIT