12 |
15 |
6 |
35 | );
36 | };
37 |
--------------------------------------------------------------------------------
/example/apps/web/README.md:
--------------------------------------------------------------------------------
1 | # React + TypeScript + Vite
2 |
3 | This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
4 |
5 | Currently, two official plugins are available:
6 |
7 | - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
8 | - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
9 |
10 | ## Expanding the ESLint configuration
11 |
12 | If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
13 |
14 | - Configure the top-level `parserOptions` property like this:
15 |
16 | ```js
17 | export default {
18 | // other rules...
19 | parserOptions: {
20 | ecmaVersion: 'latest',
21 | sourceType: 'module',
22 | project: ['./tsconfig.json', './tsconfig.node.json'],
23 | tsconfigRootDir: __dirname,
24 | },
25 | }
26 | ```
27 |
28 | - Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked`
29 | - Optionally add `plugin:@typescript-eslint/stylistic-type-checked`
30 | - Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list
31 |
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
1 | import { Hono } from "hono";
2 | import { hc } from "hono/client";
3 |
4 | import { upgrade } from "./middleware";
5 |
6 | import type { YDurableObjectsAppType } from "./yjs";
7 | import type { Env } from "hono";
8 |
9 | const app = new Hono();
10 |
11 | type Selectory-durableobjects
7 |
8 | The y-durableobjects library is designed to facilitate real-time
9 | collaboration in Cloudflare Workers environment using Yjs and Durable Objects. It provides a straightforward way
10 | to integrate Yjs for decentralized, scalable real-time editing features.
11 |
13 | GitHub:{" "} 14 | 20 | https://github.com/napolab/y-durableobjects 21 | 22 |
23 |24 | npm:{" "} 25 | 31 | https://www.npmjs.com/package/y-durableobjects 32 | 33 |
34 |
41 |
44 |
45 |
59 |
60 | );
61 | };
62 |
63 | export default Editor;
64 |
--------------------------------------------------------------------------------
/src/yjs/remote/ws-shared-doc.test.ts:
--------------------------------------------------------------------------------
1 | import { createDecoder, readVarUint } from "lib0/decoding";
2 | import { createEncoder, toUint8Array, writeVarUint } from "lib0/encoding";
3 | import { vi, describe, it, expect, beforeEach, afterEach } from "vitest";
4 | import { readSyncMessage, writeUpdate } from "y-protocols/sync";
5 | import { Doc, encodeStateAsUpdate } from "yjs";
6 |
7 | import { messageType } from "../message-type";
8 |
9 | import { WSSharedDoc } from "./ws-shared-doc";
10 |
11 | import type { Mock } from "vitest";
12 |
13 | // Helper to create updates based on document type
14 | const createYDocMessage = (content: string = "Hello World!") => {
15 | const doc = new Doc();
16 | doc.getText("root").insert(0, content);
17 |
18 | return encodeStateAsUpdate(doc);
19 | };
20 |
21 | // Helper to create an encoded message from an update
22 | const createSyncMessage = (update: Uint8Array) => {
23 | const encoder = createEncoder();
24 | writeVarUint(encoder, messageType.sync);
25 | writeUpdate(encoder, update);
26 |
27 | return toUint8Array(encoder);
28 | };
29 |
30 | // Helper to apply a received message to a new document
31 | const applyMessage = (message: Uint8Array) => {
32 | const receivedDoc = new Doc();
33 | const decoder = createDecoder(message);
34 | readVarUint(decoder);
35 | readSyncMessage(decoder, createEncoder(), receivedDoc, null);
36 |
37 | return receivedDoc;
38 | };
39 |
40 | describe("WSSharedDoc", () => {
41 | let doc: WSSharedDoc;
42 | let mockListener: Mock;
43 |
44 | beforeEach(() => {
45 | doc = new WSSharedDoc();
46 | mockListener = vi.fn();
47 | doc.notify(mockListener);
48 | });
49 |
50 | afterEach(() => {
51 | vi.restoreAllMocks();
52 | });
53 |
54 | describe("Handling Yjs Updates", () => {
55 | it("should process Yjs updates and notify listeners", () => {
56 | const update = createYDocMessage("Hello, world!");
57 | const message = createSyncMessage(update);
58 |
59 | doc.update(message);
60 |
61 | expect(mockListener).toHaveBeenCalledWith(expect.any(Uint8Array));
62 | expect(mockListener.mock.calls[0][0]).toEqual(message);
63 |
64 | const receivedDoc = applyMessage(mockListener.mock.calls[0][0]);
65 | expect(receivedDoc.getText("root").toString()).toEqual("Hello, world!");
66 | });
67 | });
68 |
69 | describe("Event Notification", () => {
70 | it("should add and remove listeners correctly", () => {
71 | const anotherListener = vi.fn();
72 | const unsubscribe = doc.notify(anotherListener);
73 | const message1 = createSyncMessage(createYDocMessage("text1"));
74 | const message2 = createSyncMessage(createYDocMessage("text2"));
75 |
76 | doc.update(message1);
77 |
78 | expect(mockListener).toHaveBeenCalledTimes(1);
79 | expect(anotherListener).toHaveBeenCalledTimes(1);
80 |
81 | unsubscribe();
82 | doc.update(message2);
83 |
84 | expect(mockListener).toHaveBeenCalledTimes(2);
85 | expect(anotherListener).toHaveBeenCalledTimes(1);
86 | });
87 | });
88 | });
89 |
--------------------------------------------------------------------------------
/CLAUDE.md:
--------------------------------------------------------------------------------
1 | # CLAUDE.md
2 |
3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 |
5 | ## Project Overview
6 |
7 | `y-durableobjects` is a library for real-time collaboration in Cloudflare Workers using Yjs and Durable Objects. It provides WebSocket-based synchronization for Yjs documents with persistent storage.
8 |
9 | ## Common Development Commands
10 |
11 | ### Build and Development
12 |
13 | - `pnpm build` - Build the library using tsup
14 | - `pnpm typecheck` - Run TypeScript type checking
15 | - `pnpm lint` - Run all linters (ESLint and Prettier)
16 | - `pnpm fmt` - Format code with Prettier and ESLint
17 | - `pnpm test` - Run tests with Vitest
18 |
19 | ### Testing
20 |
21 | - Tests use Vitest with Cloudflare Workers pool
22 | - Run a single test: `pnpm test path/to/test.test.ts`
23 | - Tests are configured with `vitest.config.ts` using Cloudflare Workers environment
24 |
25 | ### Release Process
26 |
27 | - `pnpm release` - Publish packages using changesets
28 |
29 | ## Architecture
30 |
31 | ### Core Components
32 |
33 | 1. **YDurableObjects** (`src/yjs/index.ts`)
34 |
35 | - Main Durable Object class extending Cloudflare's DurableObject
36 | - Manages WebSocket connections and Yjs document synchronization
37 | - Handles persistence through YTransactionStorage
38 | - Provides JS RPC methods: `getYDoc()` and `updateYDoc()`
39 |
40 | 2. **WSSharedDoc** (`src/yjs/remote/ws-shared-doc.ts`)
41 |
42 | - Yjs document wrapper with WebSocket notification support
43 | - Manages awareness protocol for collaborative features
44 | - Handles document updates and broadcasts
45 |
46 | 3. **YTransactionStorage** (`src/yjs/storage/index.ts`)
47 |
48 | - Persistence layer for Yjs updates
49 | - Uses Durable Object storage with transaction support
50 | - Implements incremental update storage with periodic compaction
51 |
52 | 4. **Hono Integration** (`src/index.ts`)
53 | - Provides `yRoute()` helper for easy Hono app integration
54 | - Handles WebSocket upgrade and connection routing
55 |
56 | ### Message Protocol
57 |
58 | - Uses binary WebSocket messages for Yjs synchronization
59 | - Message types defined in `src/yjs/message-type/index.ts`
60 | - Supports sync, awareness, and auth message types
61 |
62 | ### Development Constraints
63 |
64 | 1. **Cloudflare Workers Environment**
65 |
66 | - Code must be compatible with Workers runtime
67 | - Uses Cloudflare-specific APIs (DurableObject, WebSocketPair)
68 | - External imports marked in tsup config: `hono`, `/cloudflare:/`
69 |
70 | 2. **TypeScript Strict Mode**
71 |
72 | - Strict boolean expressions enforced
73 | - No explicit any allowed
74 | - Consistent type imports/exports required
75 |
76 | 3. **Code Style**
77 | - Kebab-case for filenames
78 | - No console.log in production code
79 | - Import ordering enforced by ESLint
80 | - Prettier formatting required
81 |
82 | ### Testing Approach
83 |
84 | Tests follow these patterns:
85 |
86 | - Unit tests for individual components
87 | - Integration tests using Cloudflare Workers test environment
88 | - WebSocket connection tests with mock implementations
89 | - Storage tests with in-memory implementations
90 |
--------------------------------------------------------------------------------
/src/yjs/remote/ws-shared-doc.ts:
--------------------------------------------------------------------------------
1 | import { createDecoder, readVarUint, readVarUint8Array } from "lib0/decoding";
2 | import {
3 | createEncoder,
4 | length,
5 | toUint8Array,
6 | writeVarUint,
7 | writeVarUint8Array,
8 | } from "lib0/encoding";
9 | import {
10 | applyAwarenessUpdate,
11 | Awareness,
12 | encodeAwarenessUpdate,
13 | } from "y-protocols/awareness";
14 | import { readSyncMessage, writeUpdate } from "y-protocols/sync";
15 | import { Doc } from "yjs";
16 |
17 | import { createTypedEncoder, messageType } from "../message-type";
18 |
19 | import type { AwarenessChanges, RemoteDoc } from ".";
20 |
21 | type ListenerEnter some text...
}
48 | ErrorBoundary={LexicalErrorBoundary}
49 | />
50 |
2 | 
3 |
4 |
5 | # y-durableobjects
6 |
7 | [](https://gyazo.com/e94637740dbb11fc5107b0cd0850326d)
8 |
9 | The `y-durableobjects` library is designed to facilitate real-time collaboration in the Cloudflare Workers environment using Yjs and Durable Objects. It provides a straightforward way to integrate Yjs for decentralized, scalable real-time editing features.
10 |
11 | ## Requirements
12 |
13 | - Hono version 4.3 or higher is required.
14 |
15 | ## Installation
16 |
17 | To use `y-durableobjects`, you need to install the package along with `hono`, as it is a peer dependency.
18 |
19 | ```bash
20 | npm install y-durableobjects hono
21 | ```
22 |
23 | or using yarn:
24 |
25 | ```bash
26 | yarn add y-durableobjects hono
27 | ```
28 |
29 | or pnpm:
30 |
31 | ```bash
32 | pnpm add y-durableobjects hono
33 | ```
34 |
35 | ### Configuration for Durable Objects
36 |
37 | To properly utilize Durable Objects, you need to configure bindings in your `wrangler.toml` file. This involves specifying the name of the Durable Object binding and the class name that represents your Durable Object. For detailed instructions on how to set up your `wrangler.toml` for Durable Objects, including setting up environment variables and additional resources, refer to [Cloudflare's Durable Objects documentation](https://developers.cloudflare.com/durable-objects/get-started/#5-configure-durable-object-bindings).
38 |
39 | This configuration ensures that your Cloudflare Worker can correctly instantiate and interact with Durable Objects, allowing `y-durableobjects` to manage real-time collaboration sessions.
40 |
41 | ```toml
42 | name = "your-worker-name"
43 | main = "src/index.ts"
44 | compatibility_date = "2024-04-05"
45 |
46 | account_id = "your-account-id"
47 | workers_dev = true
48 |
49 | # Durable Objects binding
50 | [durable_objects]
51 | bindings = [
52 | { name = "Y_DURABLE_OBJECTS", class_name = "YDurableObjects" }
53 | ]
54 |
55 | # Durable Objects migrations
56 | [[migrations]]
57 | tag = "v1"
58 | new_classes = ["YDurableObjects"]
59 | ```
60 |
61 | ## Usage
62 |
63 | ### With Hono shorthand
64 |
65 | ```typescript
66 | import { Hono } from "hono";
67 | import { YDurableObjects, yRoute } from "y-durableobjects";
68 |
69 | type Bindings = {
70 | Y_DURABLE_OBJECTS: DurableObjectNamespace
3 |