yjs-server

library0.2.3jsnpmunverified

An extensible, TypeScript-based WebSocket server for the Yjs collaborative editing framework, compatible with y-websocket. Version 0.2.3 (latest) is ESM-only and requires Node >=14.16. Unlike y-websocket's built-in server, yjs-server can be imported as a module, supports custom authentication with async authorization that buffers messages until resolved, and includes security fixes (e.g., against infinite loops on malformed messages). It ships TypeScript definitions. Release cadence is low; maintenance is active.

collaboration realtime

npm install yjs-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · YJS-SERVER

yjs-server

collaborationjavascriptv0.2.3

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.

createYjsServer

✓ import { createYjsServer } from 'yjs-server'

✗ const createYjsServer = require('yjs-server')

The package is ESM-only. CommonJS require() will not work.

defaultDocNameFromRequest

✓ import { defaultDocNameFromRequest } from 'yjs-server'

A helper to extract room name from URL path, useful for authorization.

type YjsServerOptions

✓ import type { YjsServerOptions } from 'yjs-server'

✗ import { YjsServerOptions } from 'yjs-server'

TypeScript users should use type import to avoid runtime import errors.

Creates a basic Yjs WebSocket server that handles collaborative editing using Y.Doc instances.

import { WebSocketServer } from 'ws' import { createYjsServer } from 'yjs-server' import * as Y from 'yjs' const wss = new WebSocketServer({ port: 8080 }) const yjss = createYjsServer({ createDoc: () => new Y.Doc(), }) wss.on('connection', (socket, request) => { yjss.handleConnection(socket, request) }) console.log('Yjs server listening on ws://localhost:8080')

Debug

Known issues

breakingThe package is ESM-only (no CommonJS). require() will throw MODULE_NOT_FOUND.

fix

Switch to ESM imports (import ... from 'yjs-server') and ensure package.json contains "type": "module" or use .mjs extension.

affects: >=0.0.1

breakinghandleConnection must be called immediately after the connection is established; otherwise, messages may be lost.

fix

Call yjss.handleConnection(socket, request) synchronously inside the 'connection' event handler.

affects: >=0.0.1

deprecatedy-websocket's built-in server is deprecated in favor of yjs-server; the API is incompatible.

fix

Migrate from y-websocket's server to yjs-server using createYjsServer and handleConnection. See README.

affects: >=0.0.1

gotchaAuthentication via async whenAuthorized promise must resolve with boolean true to authorize; otherwise connection is dropped.

fix

Ensure the promise resolves with true for authorized connections. Any other value or rejection will close the connection.

affects: >=0.0.1

gotchaThe server buffers all client messages until the whenAuthorized promise resolves. If the promise never resolves, connections stay open forever.

fix

Implement a timeout for the authorization promise to avoid resource exhaustion.

affects: >=0.0.1

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'yjs-server'

Using CommonJS require() instead of ESM import.

fix

Change to `import { createYjsServer } from 'yjs-server'` and ensure package.json has "type": "module".

TypeError: yjss.handleConnection is not a function

yjs-server is not properly imported; probably imported default instead of named import.

fix

Use `import { createYjsServer } from 'yjs-server'` and call createYjsServer to get the object with handleConnection.

Error: Connection closed with code 4001

Authorization failed; the server closed the connection with custom code 4001.

fix

Check authorization logic and ensure the whenAuthorized promise resolves with true for valid connections.

Upgrade

Version history

0.2.3latest on npm

Audit

Dependencies

lib0requiredPeer dependency: binary encoding and utility library used by Yjs

y-protocolsrequiredPeer dependency: Yjs sync and awareness protocol implementations

yjsrequiredPeer dependency: core Yjs CRDT library for document types

wsrequiredRuntime dependency: WebSocket server implementation

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/closeally/yjs-server ↗

packageyjs-server ↗

homepagehttps://github.com/closeally/yjs-server#readme ↗