⚡ socketio-kit

The Enterprise-Grade, Developer-Friendly Socket.IO SDK Wrapper for Node.js, Express & React.

Zero boilerplate. Type-safe events. Room & user emitters. React hooks. Built-in cleanup.

✨ Features

• 🔌 Zero-Boilerplate Setup: Initialize Socket.IO Client or Express Server SDK in a single line.
• 🛡️ Full TypeScript Type-Safety: Define generic event maps (ClientEvents, ServerEvents) for auto-complete and payload validation.
• ⚡ Async Acknowledgements (emitAsync): Promise-based request-response pattern with configurable timeouts.
• 🏢 Express Middleware (req.socketSdk): Seamless Express route injection with auto user room tracking (toUser, toRoom, broadcast).
• ⚛️ React Subpath (socketio-kit/react): Context provider (SocketProvider) and custom hooks (useSocket, useSocketEvent) with automatic listener cleanup on unmount.
• 🧹 Automatic Listener Cleanup: .on() returns an unsubscribe function to eliminate memory leaks.
• 🌳 Tree-Shakeable: sideEffects: false with ESM & CJS builds powered by tsup.

📦 Installation

# npm
npm install socketio-kit socket.io-client socket.io

# yarn
yarn add socketio-kit socket.io-client socket.io

# pnpm
pnpm add socketio-kit socket.io-client socket.io

💻 Quick Start

1. Express Server (socketio-kit/server)

import express from 'express';
import http from 'http';
import { socketSdk } from 'socketio-kit/server';

const app = express();
const server = http.createServer(app);

// 1. Initialize Socket.IO server
socketSdk.init(server, {
  cors: { origin: '*' },
  debug: true,
});

// 2. Attach express middleware
app.use(express.json());
app.use(socketSdk.middleware());

// 3. Emit from any route handler
app.post('/api/orders', (req, res) => {
  const { userId, item } = req.body;

  // Send targeted notification to user room ("user:123")
  req.socketSdk.toUser(userId, 'order:created', { item });

  // Broadcast to all clients
  req.socketSdk.broadcast('dashboard:update', { newOrder: item });

  res.json({ success: true });
});

server.listen(3000, () => {
  console.log('🚀 Server running on http://localhost:3000');
});

2. Client SDK (socketio-kit/client)

import { socketClient } from 'socketio-kit/client';

// Connect to server
socketClient.connect({
  url: 'http://localhost:3000',
  userId: 'user-123',
});

// Subscribe to event (returns cleanup function)
const unsubscribe = socketClient.on<{ item: string }>('order:created', (data) => {
  console.log('New order received:', data.item);
});

// Emit event
socketClient.emit('ping', { timestamp: Date.now() });

// Async Request-Response (Promise with acknowledgement)
const response = await socketClient.emitAsync<{ status: string }>('get:profile', { id: 'user-123' }, 3000);

// Cleanup listener when done
unsubscribe();

3. React Integration (socketio-kit/react)

import React from 'react';
import { SocketProvider, useSocket, useSocketEvent } from 'socketio-kit/react';

// 1. Wrap App with SocketProvider
export function App() {
  return (
    <SocketProvider config={{ url: 'http://localhost:3000', userId: 'user-123' }}>
      <OrderDashboard />
    </SocketProvider>
  );
}

// 2. Use Hooks in components
function OrderDashboard() {
  const { isConnected, client } = useSocket();
  const [orders, setOrders] = React.useState<any[]>([]);

  // Automatically subscribes on mount and unsubscribes on unmount
  useSocketEvent<{ item: string }>('order:created', (newOrder) => {
    setOrders((prev) => [...prev, newOrder]);
  });

  return (
    <div>
      <p>Status: {isConnected ? '🟢 Connected' : '🔴 Disconnected'}</p>
      <ul>
        {orders.map((o, idx) => (
          <li key={idx}>{o.item}</li>
        ))}
      </ul>
    </div>
  );
}

🛡️ Strongly Typed Events

Define custom event interfaces to enforce strict types across client and server:

interface ClientToServerEvents {
  'ping': (data: { timestamp: number }) => void;
  'chat:send': (data: { message: string }) => void;
}

interface ServerToClientEvents {
  'order:created': (data: { id: string; item: string }) => void;
  'user:status': (data: { status: 'online' | 'offline' }) => void;
}

// Client creation with generic types
import { createSocketClient } from 'socketio-kit/client';
const client = createSocketClient<ServerToClientEvents, ClientToServerEvents>();

// Type-checked emit and listeners
client.emit('chat:send', { message: 'Hello World' });
client.on('order:created', (order) => {
  console.log(order.item); // Strongly typed!
});

📖 API Reference

socketio-kit/client

| Method | Parameters | Description | | :--- | :--- | :--- | | connect(config) | SocketClientConfig | Connects client to server with query (userId) & auth options. | | disconnect() | - | Disconnects the socket. | | on(event, callback) | (event, cb) | Subscribes to an event and returns an unsubscribe function. | | once(event, callback)| (event, cb) | Subscribes to an event for one invocation. | | emit(event, data) | (event, data) | Emits event data to server. | | emitAsync(event, data, timeoutMs) | (event, data, timeout) | Emits event with acknowledgement returning Promise<T>. | | isConnected() | - | Returns boolean connection status. | | getId() | - | Returns socket connection ID. |

socketio-kit/server

| Method | Parameters | Description | | :--- | :--- | :--- | | init(server, options) | (httpServer, options) | Initializes Socket.IO server. | | middleware() | - | Returns Express middleware injecting req.socketSdk. | | toUser(userId, event, data) | (userId, event, data) | Emits event to specified user room (user:id). | | toRoom(room, event, data) | (room, event, data) | Emits event to specified room. | | broadcast(event, data) | (event, data) | Emits event to all connected clients. | | joinRoom(socketId, room) | (socketId, room) | Joins socket to a room programmatically. | | leaveRoom(socketId, room) | (socketId, room) | Removes socket from room programmatically. | | disconnectUser(userId) | (userId) | Disconnects all active sockets for user. |

🤝 Contributing

Contributions are welcome! Check out the Contributing Guide to get started.

📄 License

MIT © Doni Darmawan