Repository files navigation

WebSocket Provider for Yjs

The Websocket Provider implements a classical client server model. Clientsconnect to a single endpoint over Websocket. The server distributes awarenessinformation and document updates among clients.

This repository contains a simple in-memory backend that can persist todatabases, but it can't be scaled easily. They-redis repository contains an alternativebackend that is scalable, provides auth*, and can persist to different backends.

The Websocket Provider is a solid choice if you want a central source thathandles authentication and authorization. Websockets also send headerinformation and cookies, so you can use existing authentication mechanisms withthis server.

• Supports cross-tab communication. When you open the same document in the samebrowser, changes on the document are exchanged via cross-tab communication(BroadcastChannelandlocalStorageas fallback).
• Supports exchange of awareness information (e.g. cursors).

npm i y-websocket

There are multiple y-websocket compatible backends fory-websocket:

• @y/websocket-server
• hocuspocus

• y-sweet
• y-redis
• ypy-websocket
• pycrdt-websocket
• yrs-warp
• ...

The fastest way to get started is to run the@y/websocket-serverbackend. This package was previously included in y-websocket and now lives in aforkable repository.

Install and start y-websocket-server:

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

import*asYfrom'yjs'import{WebsocketProvider}from'y-websocket'constdoc=newY.Doc()constwsProvider=newWebsocketProvider('ws://localhost:1234','my-roomname',doc)wsProvider.on('status',event=>{console.log(event.status)// logs "connected" or "disconnected"})

The WebSocket provider requires aWebSocket object to create connection to a server. You can polyfill WebSocket support in Node.js using thews package.

constwsProvider=newWebsocketProvider('ws://localhost:1234','my-roomname',doc,{WebSocketPolyfill:require('ws')})

import{WebsocketProvider}from'y-websocket'

wsProvider = new WebsocketProvider(serverUrl: string, room: string, ydoc: Y.Doc [, wsOpts: WsOpts])

Create a new websocket-provider instance. As long as this provider, or the connected ydoc, is not destroyed, the changes will be synced to other clients via the connected server. Optionally, you may specify a configuration object. The following default values of wsOpts can be overwritten.

wsOpts={// Set this to `false` if you want to connect manually using wsProvider.connect()connect:true,// Specify a 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:{},// Object<string,string>// You may polyill the Websocket object (https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).// E.g. In nodejs, you could specify WebsocketPolyfill = require('ws')WebsocketPolyfill:Websocket,// Specify an existing Awareness instance - see https://github.com/yjs/y-protocolsawareness:newawarenessProtocol.Awareness(ydoc),// Specify the maximum amount to wait between reconnects (we use exponential backoff).maxBackoffTime:2500}

wsProvider.wsconnected: boolean

True if this instance is currently connected to the server.

wsProvider.wsconnecting: boolean

True if this instance is currently connecting to the server.

wsProvider.shouldConnect: boolean

If false, the client will not try to reconnect.

wsProvider.bcconnected: boolean

True if this instance is currently communicating to other browser-windows via BroadcastChannel.

wsProvider.synced: boolean

True if this instance is currently connected and synced with the server.

wsProvider.params : boolean

The specified url parameters. This can be safely updated, the new values will be used when a new connction is established. If this contains an auth token, it should be updated regularly.

wsProvider.disconnect()

Disconnect from the server and don't try to reconnect.

wsProvider.connect()

Establish a websocket connection to the websocket-server. Call this if you recently disconnected or if you set wsOpts.connect = false.

wsProvider.destroy()

Destroy this wsProvider instance. Disconnects from the server and removes all event handlers.

wsProvider.on('sync', function(isSynced: boolean))

Add an event listener for the sync event that is fired when the client received content from the server.

wsProvider.on('status', function({ status: 'disconnected' | 'connecting' | 'connected' }))

Receive updates about the current connection status.

wsProvider.on('connection-close', function(WSClosedEvent))

Fires when the underlying websocket connection is closed. It forwards the websocket event to this event handler.

wsProvider.on('connection-error', function(WSErrorEvent))

Fires when the underlying websocket connection closes with an error. It forwards the websocket event to this event handler.

The MIT License © Kevin Jahns