{"id":48881,"library":"partysocket","title":"PartySocket","description":"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.","status":"active","version":"1.1.19","language":"javascript","source_language":"en","source_url":"https://github.com/cloudflare/partykit","tags":["javascript","websocket","client","reconnecting","reconnection","reconnect","forever","persistent"],"install":[{"cmd":"npm install partysocket","lang":"bash","label":"npm"},{"cmd":"yarn add partysocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add partysocket","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"optional peer dependency for React components (e.g., usePartySocket)","package":"react","optional":true}],"imports":[{"note":"Named export for lower-level WebSocket constructor; default export is PartySocket","wrong":"import WebSocket from 'partysocket'","symbol":"WebSocket","correct":"import { WebSocket } from 'partysocket'"},{"note":"Default export for higher-level PartySocket; requires at least 'host' and 'room' options","wrong":"import { PartySocket } from 'partysocket'","symbol":"PartySocket","correct":"import PartySocket from 'partysocket'"},{"note":"Named export — React hook; requires react >= 17","wrong":"import usePartySocket from 'partysocket'","symbol":"usePartySocket","correct":"import { usePartySocket } from 'partysocket'"}],"quickstart":{"code":"import PartySocket from 'partysocket';\n\nconst ws = new PartySocket({\n  host: process.env.HOST ?? 'localhost:1999',\n  room: 'chat-room',\n});\n\nws.addEventListener('open', () => {\n  console.log('Connected');\n  ws.send(JSON.stringify({ type: 'join', user: 'Alice' }));\n});\n\nws.addEventListener('message', (event) => {\n  const data = JSON.parse(event.data);\n  console.log('Received:', data);\n});","lang":"typescript","description":"Shows how to create a PartySocket connection to a PartyKit room with event listeners for open and message events."},"warnings":[{"fix":"Use options object: new PartySocket({ host: '...', room: '...' }) instead of new PartySocket('wss://...', [], {...})","message":"PartySocket constructor no longer accepts a string URL as first argument when used with options; must use object configuration.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"After ws.updateProperties(...), always call ws.reconnect() to apply changes.","message":"Calling updateProperties() does not automatically reconnect; you must manually call reconnect() after.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Add 'WebSocket: require(\"ws\")' to the options object or use import WS from 'ws' and pass as WebSocket: WS.","message":"When using PartySocket in Node.js, you must provide a WebSocket polyfill (e.g., from the 'ws' package) in the options.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install 'ws' and provide it via options: new PartySocket({ host: '...', room: '...', WebSocket: WS })","message":"If 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'.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.1.19':21 'automat':10 'buffer':12,51 'built':48 'built-in':47 'bun':37 'client':60 'cloudflar':34 'connect':18 'deno':36 'depend':57 'differenti':46 'disconnect':15 'drop':4 'drop-in':3 'dynam':52 'environ':29 'forev':64 'handl':17 'independ':42 'javascript':58 'key':45 'messag':13,50 'multipl':28 'nativ':33 'node.js':31 'partykit':44 'partysocket':1 'persist':65 'provid':54 'react':32 'reconnect':11,61,62,63 'regular':25 'replac':6 'stabl':23 'support':27 'timeout':19 'updat':26 'url/protocol':53 'use':41 'version':20 'web':30 'websocket':8,59 'worker':35 'zero':56","created_at":"2026-06-07T16:58:56.790972+00:00","updated_at":"2026-06-07T16:58:56.790972+00:00","problems":[{"fix":"Use 'import PartySocket from \"partysocket\"' instead of 'import { PartySocket } from \"partysocket\"'.","cause":"Using PartySocket as a constructor but forgot to import the default export correctly.","error":"TypeError: WebSocket is not a constructor"},{"fix":"Change import to default: import PartySocket from 'partysocket'.","cause":"Using a named import for PartySocket (which expects default) and calling it as a function.","error":"Uncaught TypeError: Failed to construct 'WebSocket': Please use the 'new' operator, this DOM object constructor cannot be called as a function."},{"fix":"Provide an object with at least 'host' and 'room': new PartySocket({ host: 'myhost', room: 'myroom' }).","cause":"Constructor was called without required properties in the options object.","error":"Error: PartySocket requires 'host' and 'room' options"},{"fix":"Verify the host and port are correct and the server is running. In dev, ensure localhost:1999 is active.","cause":"Cannot connect to the WebSocket server (host not reachable).","error":"Error: connect ECONNREFUSED"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://docs.partykit.io/reference/partysocket-api","github":"https://github.com/cloudflare/partykit","docs":null,"changelog":null,"pypi":null,"npm":"partysocket","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}