partysocket

library1.1.19jsnpmunverified

A drop-in replacement for WebSocket that automatically reconnects, buffers messages while disconnected, and handles connection timeouts. Version 1.1.19 is stable with regular updates. Supports multiple environments (Web, Node.js, React Native, Cloudflare Workers, Deno, Bun) and can be used independently of PartyKit. Key differentiators: built-in message buffering, dynamic URL/protocol providers, and zero dependencies.

messaging

npm install partysocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PARTYSOCKET

partysocket

messagingjavascriptv1.1.19

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WebSocket

✓ import { WebSocket } from 'partysocket'

✗ import WebSocket from 'partysocket'

Named export for lower-level WebSocket constructor; default export is PartySocket

PartySocket

✓ import PartySocket from 'partysocket'

✗ import { PartySocket } from 'partysocket'

Default export for higher-level PartySocket; requires at least 'host' and 'room' options

usePartySocket

✓ import { usePartySocket } from 'partysocket'

✗ import usePartySocket from 'partysocket'

Named export — React hook; requires react >= 17

Shows how to create a PartySocket connection to a PartyKit room with event listeners for open and message events.

import PartySocket from 'partysocket'; const ws = new PartySocket({ host: process.env.HOST ?? 'localhost:1999', room: 'chat-room', }); ws.addEventListener('open', () => { console.log('Connected'); ws.send(JSON.stringify({ type: 'join', user: 'Alice' })); }); ws.addEventListener('message', (event) => { const data = JSON.parse(event.data); console.log('Received:', data); });

Debug

Known issues

breakingPartySocket constructor no longer accepts a string URL as first argument when used with options; must use object configuration.

fix

Use options object: new PartySocket({ host: '...', room: '...' }) instead of new PartySocket('wss://...', [], {...})

affects: >=1.0.0

deprecatedCalling updateProperties() does not automatically reconnect; you must manually call reconnect() after.

fix

After ws.updateProperties(...), always call ws.reconnect() to apply changes.

affects: >=1.0.0

gotchaWhen using PartySocket in Node.js, you must provide a WebSocket polyfill (e.g., from the 'ws' package) in the options.

fix

Add 'WebSocket: require("ws")' to the options object or use import WS from 'ws' and pass as WebSocket: WS.

affects: >=1.0.0

gotchaIf no custom WebSocket constructor is provided and global WebSocket is unavailable (e.g., in Node.js without polyfill), PartySocket will throw 'WebSocket is not defined'.

fix

Install 'ws' and provide it via options: new PartySocket({ host: '...', room: '...', WebSocket: WS })

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: WebSocket is not a constructor

Using PartySocket as a constructor but forgot to import the default export correctly.

fix

Use 'import PartySocket from "partysocket"' instead of 'import { PartySocket } from "partysocket"'.

Uncaught TypeError: Failed to construct 'WebSocket': Please use the 'new' operator, this DOM object constructor cannot be called as a function.

Using a named import for PartySocket (which expects default) and calling it as a function.

fix

Change import to default: import PartySocket from 'partysocket'.

Error: PartySocket requires 'host' and 'room' options

Constructor was called without required properties in the options object.

fix

Provide an object with at least 'host' and 'room': new PartySocket({ host: 'myhost', room: 'myroom' }).

Error: connect ECONNREFUSED

Cannot connect to the WebSocket server (host not reachable).

fix

Verify the host and port are correct and the server is running. In dev, ensure localhost:1999 is active.

Upgrade

Version history

1.1.19latest on npm

Audit

Dependencies

reactoptionaloptional peer dependency for React components (e.g., usePartySocket)

Agent activity

16 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/cloudflare/partykit ↗

packagepartysocket ↗

homepagehttps://docs.partykit.io/reference/partysocket-api ↗