y-websocket

The fastest way to get started is to use the @y/websocket-server backend. This package is a standalone backend compatible with the y-websocket provider.

Install and start the server using the following commands:

npm install @y/websocket-server
HOST=localhost PORT=1234 npx y-websocket

You can install the stable release (recommended for Yjs v13) or the unstable development branch (for Yjs v14 support).

Stable release (recommended):

npm i y-websocket

Main branch / unstable release:

npm i @y/websocket

# stable release (recommended)
npm i y-websocket

# main branch / unstable release
npm i @y/websocket

When instantiating WebsocketProvider, you can pass an optional wsOpts object to customize connection behavior.

wsOpts = {
  // Set this to `false` if you want to connect manually using wsProvider.connect()
  connect: true,
  // Specify query-string / url parameters that will be url-encoded and attached to the `serverUrl`
  // I.e. params = { auth: "bearer" } will be transformed to "?auth=bearer"
  params: {},
  // You may polyfill the Websocket object (e.g. in Node.js)
  WebsocketPolyfill: Websocket,
  // Specify an existing Awareness instance
  awareness: new awarenessProtocol.Awareness(ydoc),
  // Specify the maximum amount to wait between reconnects (exponential backoff)
  maxBackoffTime: 2500
}

To connect a Yjs document to a remote server, use the WebsocketProvider. It synchronizes the Y.Doc with the server and handles awareness (e.g., cursor positions) and document updates.

import * as Y from '@y/y'
import { WebsocketProvider } from 'y-websocket'

const doc = new Y.Doc()
const wsProvider = new WebsocketProvider('ws://localhost:1234', 'my-roomname', doc)

wsProvider.on('status', event => {
  console.log(event.status) // logs "connected" or "disconnected"
})

Since Node.js does not have a native WebSocket implementation, you must provide a polyfill (such as the ws package) via the WebsocketPolyfill option in the configuration object.

const wsProvider = new WebsocketProvider('ws://localhost:1234', 'my-roomname', doc, { WebSocketPolyfill: require('ws') })

Use these methods to control the lifecycle of the provider:

• wsProvider.disconnect(): Disconnect from the server and prevent reconnection.
• wsProvider.connect(): Establish a connection. Use this if you previously called disconnect() or if wsOpts.connect was set to false.
• wsProvider.destroy(): Disconnect from the server and remove all event handlers.

The WebsocketProvider instance exposes several properties to monitor connection and synchronization state:

• wsconnected: boolean - True if currently connected to the server.
• wsconnecting: boolean - True if currently connecting to the server.
• shouldConnect: boolean - If false, the client will not try to reconnect.
• bcconnected: boolean - True if communicating with other browser windows via BroadcastChannel.
• synced: boolean - True if connected and synced with the server.
• syncStatus: SyncStatus - Detailed sync status (works with certain backends like yhub).
• params: Object<string,string> - The specified URL parameters. Can be updated to refresh connection with new values (e.g. auth tokens).
• wsProvider.params: boolean - (Note: The documentation lists this as boolean, but context implies it refers to the params object/status).

The WebsocketProvider emits several events for monitoring lifecycle and synchronization:

• wsProvider.on('sync', (isSynced: boolean) => ...): Fired when the client receives content from the server.
• wsProvider.on('status', ({ status: 'disconnected' | 'connecting' | 'connected' }) => ...): Updates on the current connection status.
• wsProvider.on('connection-close', (WSClosedEvent) => ...): Fired when the underlying WebSocket connection is closed.
• wsProvider.on('connection-error', (WSErrorEvent) => ...): Fired when the connection closes with an error.
• wsProvider.on('sync-status', (syncStatus: SyncStatus) => ...): Detailed sync status updates (works with certain backends like yhub).

The WebsocketProvider class is used to create a WebSocket connection to a server to synchronize a Yjs document (Y.Doc) and its awareness state. The document name is appended to the provided serverUrl as a path component.

To use it, instantiate WebsocketProvider with the server URL, a room name, and your Y.Doc instance. By default, it connects immediately upon instantiation.

```ts
import * as Y from '@y/y'
import { WebsocketProvider } from 'y-websocket'

const doc = new Y.Doc()
const provider = new WebsocketProvider('http://localhost:1234', 'my-document-name', doc)
```埋

WebsocketProvider extends ObservableV2 and emits several events to track the connection and synchronization status.

Supported Events