y-durableobjects

The y-durableobjects project provides a way to integrate Yjs (a real-time collaboration framework) with Cloudflare Workers using Durable Objects.

This architecture is designed to:

• Eliminate the dependency on Node.js for real-time collaboration.
• Provide a scalable and efficient solution inspired by the y-websocket adapter.
• Enable real-time collaborative applications to run on the Cloudflare edge.

To start the development environment for the workers package, install the dependencies and run the development script.

npm install
npm run dev

For production applications, it is recommended to enable type-aware lint rules in your ESLint configuration. This requires updating parserOptions to point to your tsconfig files and switching to type-checked plugin recommendations.

Steps to upgrade:

1. Update parserOptions to include project and tsconfigRootDir.
2. Replace plugin:@typescript-eslint/recommended with plugin:@typescript-eslint/recommended-type-checked or plugin:@typescript-eslint/strict-type-checked.
3. (Optional) Add plugin:@typescript-eslint/stylistic-type-checked.
4. Install eslint-plugin-react and add plugin:react/recommended and plugin:react/jsx-runtime to the extends array.

export default {
  // other rules...
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: ['./tsconfig.json', './tsconfig.node.json'],
    tsconfigRootDir: __dirname,
  },
}

To use y-durableobjects, install it along with hono (a required peer dependency).

npm install y-durableobjects hono

Or using other package managers:

yarn add y-durableobjects hono

pnpm add y-durableobjects hono

To use typed WebSocket communications on the client, use Hono's hc client. This leverages the Hono WebSocket Helper, making the $ws method available.

1. Server Setup

Ensure your server exports the AppType (either via yRoute shorthand or manual implementation).

2. Client Implementation

import { hc } from "hono/client";
import type { AppType } from "./server"; // Import the type from your server file

const API_URL = "http://localhost:8787";

// Create a typed client
export const client = hc<AppType>(API_URL);

// Access the WebSocket endpoint
const ws = client.editor[":id"].$ws({ param: { id: "example" } });
// ws is now a typed WebSocket

To deploy the workers example to your environment, use the deploy command.

npm run deploy

You must configure Durable Object bindings and migrations in your wrangler.toml file to allow your Worker to interact with y-durableobjects.

Specifically, you need to define a binding with a class_name of YDurableObjects (or your custom subclass) and include a migration to create that class.

Example wrangler.toml configuration:

# Durable Objects binding
[durable_objects]
bindings = [
  { name = "Y_DURABLE_OBJECTS", class_name = "YDurableObjects" }
]

# Durable Objects migrations
[[migrations]]
tag = "v1"
new_classes = ["YDurableObjects"]

If you see TypeScript errors where Cloudflare.Env is empty or undefined, it is likely because @cloudflare/workers-types (a peer dependency) is creating an empty interface that overwrites your custom environment types.

Solution

1. Generate fresh types: Use Wrangler to generate types based on your actual configuration.

   wrangler types

2. Perform a clean install: If the issue persists, clear your dependency cache to remove residual @cloudflare/workers-types entries.

   # Delete lock files and node_modules
   rm -rf node_modules pnpm-lock.yaml
   # Reinstall dependencies
   pnpm install

3. Verify: Run pnpm why @cloudflare/workers-types. It should return no results if the conflict is resolved.

The easiest way to integrate y-durableobjects with Hono is using the yRoute shorthand. This automatically handles the routing for real-time collaboration.

import { Hono } from "hono";
import { YDurableObjects, yRoute } from "y-durableobjects";

type Bindings = {
  Y_DURABLE_OBJECTS: DurableObjectNamespace<YDurableObjects<Env>>;
};

type Env = {
  Bindings: Bindings;
};

const app = new Hono<Env>();

// The yRoute helper sets up the collaboration endpoint
const route = app.route(
  "/editor",
  yRoute<Env>((env) => env.Y_DURABLE_OBJECTS),
);

export default route;
export type AppType = typeof route;
export { YDurableObjects };

You can extend the YDurableObjects class to implement custom logic and expose new methods via JS RPC. You have access to the internal this.doc (the YDoc instance).

import { YDurableObjects } from "y-durableobjects";

export class CustomDurableObject extends YDurableObjects {
  async customMethod() {
    // Access and manipulate the YDoc state directly
    const update = new Uint8Array([
      /* some update data */
    ]);
    this.doc.update(update);
    
    // You can also call cleanup manually if needed
    await this.cleanup();
  }
}

import { YDurableObjects } from "y-durableobjects";

export class CustomDurableObject extends YDurableObjects {
  async customMethod() {
    const update = new Uint8Array([/* ... */]);
    this.doc.update(update);
    await this.cleanup();
  }
}