yjs-cf-ws-provider: A Yjs WebSocket Provider on Cloudflare Workers

Summary

The yjs-cf-ws-provider project offers a serverless WebSocket provider for Yjs, leveraging Cloudflare Workers and Durable Objects. It is designed for learning and demonstrating Cloudflare's powerful APIs, providing a cost-effective and scalable solution for real-time collaboration. This provider is fully compatible with the Yjs WebSocket Connector.

Use at your own risk

OSRepos shares public repositories for knowledge and discovery only. Any installation, execution, configuration, or use of code from these repositories is the user's own responsibility. Always review the repository, source code, dependencies, licenses, and security implications before running or installing anything. OSRepos is not responsible for issues, damages, or losses resulting from third-party repositories.

Introduction

The yjs-cf-ws-provider project offers a serverless WebSocket provider specifically designed for Yjs, running efficiently on Cloudflare Workers. It utilizes Cloudflare Durable Objects to manage state and relay messages between clients, ensuring robust real-time synchronization. A notable feature is its use of the Cloudflare Durable Objects WebSocket Hibernation API, which terminates idle WebSocket connections to minimize duration charges. Additionally, it periodically saves Yjs document states to Cloudflare R2 storage, clearing partial updates from Durable Object storage to optimize performance and cost. This provider is fully compatible with the official Yjs WebSocket Connector.

Please note, this project is primarily intended for learning purposes and to demonstrate the capabilities of Cloudflare Workers and Durable Objects APIs. For production-ready solutions, consider alternatives like PartyKit, which also supports the Yjs API.

Installation

To run this project locally, follow these steps:

npm install
npm run dev

This command will start a local server using the Wrangler CLI and serve a demo application. You can then open a browser to the URL displayed in the console to test it with a simple TipTap editor.

Examples

The local development setup includes a demo application, allowing you to easily test the provider with a basic TipTap editor in your browser. This provides a practical example of how the Yjs WebSocket provider integrates with a collaborative text editor.

Why Use It

Serverless & Scalable: Leveraging Cloudflare Workers and Durable Objects, this provider offers a highly scalable and serverless solution for Yjs real-time collaboration.
Cost-Effective: The innovative use of WebSocket Hibernation significantly reduces operational costs by preventing charges for idle connections.
Data Persistence: Integration with Cloudflare R2 ensures that Yjs document states are persistently stored and regularly optimized.
Educational Value: It serves as an excellent resource for developers looking to understand and implement Cloudflare's powerful serverless and state management APIs.
Yjs Ecosystem: Its full compatibility with the Yjs WebSocket Connector makes it a seamless fit within existing Yjs-based applications.