{"id":49806,"library":"y-websocket","title":"Y-WebSocket","description":"WebSocket provider for Yjs that enables real-time synchronization of Yjs documents over WebSocket connections. Version 3.0.0 requires Yjs ^13.5.6 and Node.js >=16. Published regularly with stable API. Key differentiator: official Yjs WebSocket binding supporting server-side broadcasting and client-side awareness. Lightweight, no additional dependencies beyond yjs. Ideal for collaborative editing applications.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/yjs/y-websocket","tags":["javascript","Yjs","typescript"],"install":[{"cmd":"npm install y-websocket","lang":"bash","label":"npm"},{"cmd":"yarn add y-websocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add y-websocket","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for document model and synchronization","package":"yjs","optional":false}],"imports":[{"note":"ESM-only; CommonJS require() will fail. Use dynamic import if needed.","wrong":"const WebsocketProvider = require('y-websocket')","symbol":"WebsocketProvider","correct":"import { WebsocketProvider } from 'y-websocket'"},{"note":"Typical server-side import. Ensure y-websocket is installed alongside yjs.","wrong":"","symbol":"WebSocketServer","correct":"import { WebSocketServer } from 'y-websocket'"},{"note":"Utility for handling WebSocket connections on the server.","wrong":"const { setupWSConnection } = require('y-websocket')","symbol":"setupWSConnection","correct":"import { setupWSConnection } from 'y-websocket'"}],"quickstart":{"code":"import * as Y from 'yjs';\nimport { WebsocketProvider } from 'y-websocket';\n\nconst doc = new Y.Doc();\nconst wsProvider = new WebsocketProvider('ws://localhost:1234', 'my-room', doc);\nwsProvider.on('status', (event) => {\n  console.log('Status:', event.status);\n});\n\nconst yarray = doc.getArray('items');\nyarray.observeDeep(() => {\n  console.log('Items updated:', yarray.toArray());\n});\nconsole.log('Provider ready');","lang":"typescript","description":"Creates a Yjs document and connects to a WebSocket server for real-time collaboration."},"warnings":[{"fix":"Use import syntax or dynamic import() in Node.js.","message":"ESM-only; CommonJS require() throws error.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure room name matches /^[a-zA-Z0-9_-]+$/.","message":"WebSocketProvider constructor requires 'ws' URL and room name; room name must be alphanumeric.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Update yjs to ^13.5.6 or later.","message":"Yjs peer dependency version: ^13.5.6; older Yjs versions incompatible.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use { doc: yDoc } as option parameter.","message":"setupWSConnection parameters changed; 'doc' option must be provided.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Implement custom reconnection logic if needed.","message":"WebSocket server must be running; no automatic reconnection if server down.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'13.5.6':24 '16':27 '3.0.0':21 'addit':51 'api':32 'applic':59 'awar':48 'beyond':53 'bind':38 'broadcast':43 'client':46 'client-sid':45 'collabor':57 'connect':19 'depend':52 'differenti':34 'document':16 'edit':58 'enabl':9 'ideal':55 'javascript':60 'key':33 'lightweight':49 'node.js':26 'offici':35 'provid':5 'publish':28 'real':11 'real-tim':10 'regular':29 'requir':22 'server':41 'server-sid':40 'side':42,47 'stabl':31 'support':39 'synchron':13 'time':12 'typescript':62 'version':20 'websocket':3,4,18,37 'y':2 'y-websocket':1 'yjs':7,15,23,36,54,61","created_at":"2026-06-07T17:03:41.864619+00:00","updated_at":"2026-06-07T17:03:41.864619+00:00","problems":[{"fix":"Change require() to import statement or use dynamic import().","cause":"Using CommonJS require() to import y-websocket which is ESM-only.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module"},{"fix":"Use { WebsocketProvider } from 'y-websocket'.","cause":"Importing wrong symbol or using default import instead of named import.","error":"TypeError: WebsocketProvider is not a constructor"},{"fix":"Install ws: npm install ws","cause":"Missing ws module when using WebSocketServer on server side.","error":"Error: Cannot find module 'ws'"}],"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://github.com/yjs/y-websocket#readme","github":"https://github.com/yjs/y-websocket","docs":null,"changelog":null,"pypi":null,"npm":"y-websocket","openapi_spec":null,"status_page":null,"smithery":null,"categories":["collaboration","realtime"],"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}}