y-websocket

library3.0.0jsnpmunverified

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.

collaboration realtime

npm install y-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · Y-WEBSOCKET

y-websocket

collaborationjavascriptv3.0.0

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.

WebsocketProvider

✓ import { WebsocketProvider } from 'y-websocket'

✗ const WebsocketProvider = require('y-websocket')

ESM-only; CommonJS require() will fail. Use dynamic import if needed.

WebSocketServer

✓ import { WebSocketServer } from 'y-websocket'

Typical server-side import. Ensure y-websocket is installed alongside yjs.

setupWSConnection

✓ import { setupWSConnection } from 'y-websocket'

✗ const { setupWSConnection } = require('y-websocket')

Utility for handling WebSocket connections on the server.

Creates a Yjs document and connects to a WebSocket server for real-time collaboration.

import * as Y from 'yjs'; import { WebsocketProvider } from 'y-websocket'; const doc = new Y.Doc(); const wsProvider = new WebsocketProvider('ws://localhost:1234', 'my-room', doc); wsProvider.on('status', (event) => { console.log('Status:', event.status); }); const yarray = doc.getArray('items'); yarray.observeDeep(() => { console.log('Items updated:', yarray.toArray()); }); console.log('Provider ready');

Debug

Known issues

breakingESM-only; CommonJS require() throws error.

fix

Use import syntax or dynamic import() in Node.js.

affects: >=3.0.0

gotchaWebSocketProvider constructor requires 'ws' URL and room name; room name must be alphanumeric.

fix

Ensure room name matches /^[a-zA-Z0-9_-]+$/.

affects: >=0.0.0

breakingYjs peer dependency version: ^13.5.6; older Yjs versions incompatible.

fix

Update yjs to ^13.5.6 or later.

affects: >=3.0.0

deprecatedsetupWSConnection parameters changed; 'doc' option must be provided.

fix

Use { doc: yDoc } as option parameter.

affects: >=2.0.0

gotchaWebSocket server must be running; no automatic reconnection if server down.

fix

Implement custom reconnection logic if needed.

affects: >=0.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

Using CommonJS require() to import y-websocket which is ESM-only.

fix

Change require() to import statement or use dynamic import().

TypeError: WebsocketProvider is not a constructor

Importing wrong symbol or using default import instead of named import.

fix

Use { WebsocketProvider } from 'y-websocket'.

Error: Cannot find module 'ws'

Missing ws module when using WebSocketServer on server side.

fix

Install ws: npm install ws

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

yjsrequiredPeer dependency required for document model and synchronization

Agent activity

51 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/yjs/y-websocket ↗

packagey-websocket ↗

homepagehttps://github.com/yjs/y-websocket#readme ↗