Registry / devops / y-multiplex-websocket-server

y-multiplex-websocket-server

library0.3.0jsnpmunverified

A multiplex-first Yjs WebSocket server and client provider that allows a single physical WebSocket to carry multiple routed Yjs documents under the same namespace. Supports awareness, optional BroadcastChannel sync, optional persistence via callback, and optional NATS cluster sync. The stable version 0.3.0 requires yjs ^13 || ^14 and Node >=16 with npm >=8. Unlike y-websocket which spawns a separate WebSocket per document, this package reuses one connection per namespace, reducing overhead. Ships a bundled CLI for quick start and exports low-level utilities for custom server wiring. Active development.

devops

npm install y-multiplex-websocket-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · Y-MULTIPLEX-WEBSOC

y-multiplex-websocket-server

devopsjavascriptv0.3.0

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.

MultiplexProvider

✓ import { MultiplexProvider } from 'y-multiplex-websocket-server/multiplex-provider'

✗ const MultiplexProvider = require('y-multiplex-websocket-server')

This is a named export from a subpath; no default export. ESM-only.

setupWSConnection

✓ import { setupWSConnection } from 'y-multiplex-websocket-server/utils-connection'

✗ import { setupWSConnection } from 'y-multiplex-websocket-server'

Utility function from a separate module; not re-exported from package root.

getDoc

✓ import { getDoc } from 'y-multiplex-websocket-server/utils-docs'

Import from utils-docs alongside other doc utilities.

Demonstrates creating a Yjs document, attaching it via MultiplexProvider under namespace 'ticket' and docName 'version', and listening for connection status.

import * as Y from 'yjs' import { MultiplexProvider } from 'y-multiplex-websocket-server/multiplex-provider' const doc = new Y.Doc() const provider = new MultiplexProvider('ws://localhost:1234/connect/doc', 'ticket', { params: { token: 'demo-token' } }) const binding = provider.attach('version', doc, { awareness: true }) binding.on('status', evt => { console.log(evt.status) }) // Start server via npx y-websocket-multiplex-server with defaults

Debug

Known issues

gotchaSubpath imports are not re-exported from package root; you must import from specific subpaths like 'y-multiplex-websocket-server/multiplex-provider'.

fix

Import from exact subpath as shown in documentation.

affects: >=0.1.0

gotchaMultiplexProvider requires both a server URL and a namespace; omitting namespace results in connection failure.

fix

Always provide a namespace string as second argument to MultiplexProvider constructor.

affects: >=0.1.0

breakingIn version 0.3.0, the CLI binary name changed from 'y-websocket-multiplex-server' to 'y-websocket-multiplex-server' (same as package; but previously it might have been different).

fix

Use 'npx y-websocket-multiplex-server' instead of older binary name.

affects: 0.2.x

deprecatedUsing 'require' syntax will fail as the package is ESM-only.

fix

Use ES module imports (import) or ensure your project is configured for ESM.

affects: >=0.3.0

gotchaThe 'WebSocketPolyfill' option is required in Node.js environments where global WebSocket is not available.

fix

Pass a WebSocket constructor (e.g., from 'ws' package) as opts.WebSocketPolyfill when running in Node.

affects: >=0.1.0

gotchaNATS sync will silently fail if NATS servers are not reachable; no error is thrown.

fix

Ensure NATS_SERVERS env var is correctly set and NATS cluster is running.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'y-multiplex-websocket-server' or its corresponding type declarations.

Attempting to import from package root instead of subpath.

fix

import { MultiplexProvider } from 'y-multiplex-websocket-server/multiplex-provider'

TypeError: provider.attach is not a function

Using import { MultiplexProvider } from 'y-multiplex-websocket-server' which is undefined.

fix

Use correct subpath import as shown in documentation.

ReferenceError: WebSocket is not defined

Running in Node.js without providing a WebSocket polyfill.

fix

Add opts.WebSocketPolyfill: WebSocket (from 'ws' package) to the MultiplexProvider constructor.

Error: Unexpected server response: 404

Server URL path is incorrect; /connect/doc is required as base path.

fix

Use server URL like 'ws://localhost:1234/connect/doc'

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

yjsrequiredPeer dependency for Yjs document types and synchronization protocol

wsrequiredRequired for server-side WebSocket implementation (used internally)

natsoptionalOptional for NATS cluster sync; not required unless using NATS

Agent activity

17 hits · last 30 days

node

Resources

githubhttps://github.com/CyrusNG/y-multiplex-websocket-server ↗

packagey-multiplex-websocket-server ↗

homepagehttps://github.com/CyrusNG/y-multiplex-websocket-server#readme ↗