Introduction

Real-time communication library for serverless environments

socket-serve

socket-serve is a TypeScript library that provides real-time, bidirectional communication for serverless platforms. It offers a socket.io-compatible API but uses HTTP-based transports (SSE and polling) instead of WebSockets, making it work on platforms that don’t support persistent connections.

Installation

npm

npm install socket-serve ioredis

Version: 1.0.0 (npm)

Overview

Traditional WebSocket libraries require persistent connections, which are incompatible with serverless architectures. socket-serve addresses this limitation by using:

• Server-Sent Events (SSE) for server-to-client communication
• HTTP POST for client-to-server communication
• Redis for state management and pub/sub across serverless instances
• Automatic reconnection with exponential backoff
• Message acknowledgments for request/response patterns

Features

• Serverless-first architecture without persistent connections
• Multiple transport support with SSE as primary and polling as fallback
• Room-based broadcasting with advanced room operations
• Message acknowledgments with timeout handling
• Edge Runtime support for Vercel and Cloudflare Workers
• Binary data and message compression support
• Presence tracking and user status management
• Middleware and namespace support
• Full TypeScript support with type definitions
• Framework adapters for Next.js and Express
• Automatic client reconnection with exponential backoff

Quick Example

Server (Next.js)

import { createSocketServer } from 'socket-serve';
import { createNextJSAdapter } from 'socket-serve/adapters';

const server = createSocketServer({
  redisUrl: process.env.REDIS_URL!
});

server.on('connection', (socket) => {
  console.log('Client connected:', socket.id);
  
  socket.on('message', (data) => {
    socket.emit('response', { received: data });
  });
  
  socket.join('lobby');
  socket.broadcastToRoom('lobby', 'user-joined', { userId: socket.id });
});

export const { GET, POST } = createNextJSAdapter(server);

Client (Browser)

import { connect } from 'socket-serve/client';

const socket = connect('https://your-app.vercel.app/api/socket');

socket.on('connect', () => {
  console.log('Connected:', socket.id);
});

socket.emit('message', { text: 'Hello!' });

socket.on('response', (data) => {
  console.log('Received:', data);
});

Architecture

The library uses HTTP-based transports instead of WebSockets:

Client to Server: HTTP POST requests Server to Client: Server-Sent Events (SSE) or HTTP polling State Management: Redis for session state and pub/sub Broadcasting: Redis pub/sub for multi-instance coordination

See Architecture for detailed information.

When to Use

Use socket-serve when:

• Deploying to serverless platforms (Vercel, AWS Lambda, etc.)
• WebSocket connections are blocked by infrastructure
• Horizontal scaling without sticky sessions is required
• Redis is already part of your stack

Consider alternatives when:

• Running on traditional servers with WebSocket support
• Ultra-low latency is critical (WebSockets provide lower latency)
• Redis infrastructure is not available

Comparison with WebSockets

Aspect	WebSocket	socket-serve
Connection Type	Persistent TCP	HTTP-based
Serverless Support	No	Yes
Latency	10-50ms	50-200ms (SSE) / 1000ms (polling)
Infrastructure	Simple	Requires Redis
Proxy Compatibility	Variable	High
Scaling	Requires sticky sessions	Stateless

Documentation

• Installation - Setup and configuration
• Quickstart - Build your first application
• API Reference - Complete API documentation
• Examples - Sample applications
• Concepts - How it works

Resources

• Documentation: socket-serve.mintlify.app
• GitHub: rohandol112/socket-serve
• npm: socket-serve
• Issues: GitHub Issues