Getting Started

itty-sockets is a tiny WebSocket relay client. Connect to a channel, send messages, and everyone on that channel receives them in real-time.

Install

npm install itty-sockets

Or with your preferred package manager:

bun add itty-sockets
pnpm add itty-sockets
yarn add itty-sockets

Quick Start

import { connect } from 'itty-sockets'

const channel = connect('my-channel')

// listen for messages
channel.on('message', ({ message, uid, alias }) => {
  console.log(`${alias || uid}: ${message}`)
})

// send a message
channel.send('hello world')

That's it. No accounts, no API keys, no server. The channel is created automatically when the first client connects, and destroyed when the last one disconnects.

Connection Options

The connect function accepts an optional second argument with configuration:

connect('my-channel', {
  as: 'Alice',          // display name (alias)
  echo: true,           // receive your own messages back
  announce: true,       // include uid/alias in join/leave events
  joinKey: 'secret',    // required if channel has a join key
  sendKey: 'secret',    // required if channel has a send key
})

API at a Glance

Method	Description
`.on(type, listener)`	Listen for events — see Receiving Messages
`.send(message)`	Broadcast to channel — see Sending Messages
`.send(message, uid)`	Private message to a user
`.push(message)`	Send then disconnect
`.open()`	Reconnect (safe to call anytime)
`.close()`	Disconnect
`.remove(type, fn)`	Unregister a listener

All methods are chainable and return the socket instance.

Next: Channels — learn how channels work and how to organize them.