https://github.com/yjs/y-websocket

Websocket Connector for Yjs
https://github.com/yjs/y-websocket

yjs yjs-provider

Last synced: 2 months ago
JSON representation

Websocket Connector for Yjs

• Host: GitHub
• URL: https://github.com/yjs/y-websocket
• Owner: yjs
• License: mit
• Created: 2019-02-05T12:26:24.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2026-03-24T23:37:07.000Z (3 months ago)
• Last Synced: 2026-03-26T03:57:48.627Z (3 months ago)
• Topics: yjs, yjs-provider
• Language: JavaScript
• Homepage: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket
• Size: 811 KB
• Stars: 689
• Watchers: 16
• Forks: 318
• Open Issues: 42
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# y-websocket :tophat:

> WebSocket Provider for Yjs

The Websocket Provider implements a classical client server model. Clients

connect to a single endpoint over Websocket. The server distributes awareness

information and document updates among clients.

This repository contains a simple in-memory backend that can persist to

databases, but it can't be scaled easily. The

[y-redis](https://github.com/yjs/y-redis/) repository contains an alternative

backend that is scalable, provides auth*, and can persist to different backends.

The Websocket Provider is a solid choice if you want a central source that

handles authentication and authorization. Websockets also send header

information and cookies, so you can use existing authentication mechanisms with

this server.

* Supports cross-tab communication. When you open the same document in the same

browser, changes on the document are exchanged via cross-tab communication

([Broadcast

Channel](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API)

and

[localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)

as fallback).

* Supports exchange of awareness information (e.g. cursors).

## Quick Start

### Install dependencies

```sh

npm i y-websocket

```

### Start a y-websocket server

There are multiple y-websocket compatible backends for `y-websocket`: 

* [@y/websocket-server](https://github.com/yjs/y-websocket-server/)

* hocuspocus

- y-sweet

- y-redis

- ypy-websocket

- pycrdt-websocket

- [yrs-warp](https://github.com/y-crdt/yrs-warp)

- ...

The fastest way to get started is to run the [@y/websocket-server](https://github.com/yjs/y-websocket-server/)

backend. This package was previously included in y-websocket and now lives in a

forkable repository.

Install and start y-websocket-server:

```sh

npm install @y/websocket-server

HOST=localhost PORT=1234 npx y-websocket

```

### Client Code:

```js

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"

})

```

#### Client Code in Node.js

The WebSocket provider requires a [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) object to create connection to a server. You can polyfill WebSocket support in Node.js using the [`ws` package](https://www.npmjs.com/package/ws).

```js

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

```

## API

```js

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. 



```js

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

  // 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-protocols

  awareness: new awarenessProtocol.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.syncStatus: SyncStatus

  
The current sync status object containing connected, receivedInitialSync, localUpdatesSynced, localUpdatesAge, lastMessageAge, and status ('green', 'yellow', or 'red'). See the 'sync-status' event for details. Only works with certain backends (e.g. yhub).

  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.

  wsProvider.on('sync-status', function(syncStatus: SyncStatus))

  


    Receive detailed sync status updates. This event fires when the sync status changes, providing a distilled view of the connection and synchronization state. Only works with certain backends (e.g. yhub).

    



    The syncStatus object has the following properties:

    


      


connected: boolean – Whether the provider is currently connected to the server.

      


receivedInitialSync: boolean – Whether the initial sync with the server has completed.

      


localUpdatesSynced: boolean – Whether all local updates have been confirmed by the server.

      


localUpdatesAge: number – Age in milliseconds of the oldest unconfirmed local update (0 if all synced).

      


lastMessageAge: number – Time in milliseconds since the last message was received from the server.

      


status: 'green' | 'yellow' | 'red' – Distilled sync status:

        


          


'green' – Connected, synced, and no unconfirmed local updates.

          


'yellow' – Connected but has unconfirmed local updates younger than 8 seconds.

          


'red' – Disconnected, not synced, or unconfirmed local updates older than 8 seconds.

        

      

    

    The current sync status can also be accessed directly via wsProvider.syncStatus.

  



## License

[The MIT License](./LICENSE) © Kevin Jahns