https://github.com/yjs/y-websocket
Websocket Connector for Yjs
https://github.com/yjs/y-websocket
yjs yjs-provider
Last synced: 10 days 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 6 years ago)
- Default Branch: master
- Last Pushed: 2025-04-02T22:20:39.000Z (about 2 months ago)
- Last Synced: 2025-05-08T19:12:52.623Z (15 days ago)
- Topics: yjs, yjs-provider
- Language: JavaScript
- Homepage: https://docs.yjs.dev/ecosystem/connection-provider/y-websocket
- Size: 317 KB
- Stars: 589
- Watchers: 17
- Forks: 287
- Open Issues: 39
-
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 'yjs'
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'
```
- 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.
wsProvider = new WebsocketProvider(serverUrl: string, room: string, ydoc: Y.Doc [, wsOpts: WsOpts])
```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
}
```
- True if this instance is currently connected to the server.
- True if this instance is currently connecting to the server.
- If false, the client will not try to reconnect.
- True if this instance is currently communicating to other browser-windows via BroadcastChannel.
- True if this instance is currently connected and synced with the server.
- 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. - Disconnect from the server and don't try to reconnect.
- Establish a websocket connection to the websocket-server. Call this if you recently disconnected or if you set wsOpts.connect = false.
- Destroy this wsProvider instance. Disconnects from the server and removes all event handlers.
- Add an event listener for the sync event that is fired when the client received content from the server.
- Receive updates about the current connection status.
- Fires when the underlying websocket connection is closed. It forwards the websocket event to this event handler.
- Fires when the underlying websocket connection closes with an error. It forwards the websocket event to this event handler.
wsProvider.wsconnected: boolean
wsProvider.wsconnecting: boolean
wsProvider.shouldConnect: boolean
wsProvider.bcconnected: boolean
wsProvider.synced: boolean
wsProvider.params : boolean
wsProvider.disconnect()
wsProvider.connect()
wsProvider.destroy()
wsProvider.on('sync', function(isSynced: boolean))
wsProvider.on('status', function({ status: 'disconnected' | 'connecting' | 'connected' }))
wsProvider.on('connection-close', function(WSClosedEvent))
wsProvider.on('connection-error', function(WSErrorEvent))
## License
[The MIT License](./LICENSE) © Kevin Jahns