@groundstate/cloudflare

Cloudflare Durable Objects adapter for running @groundstate sync at the edge.

Installation

# npm
npm install @groundstate/cloudflare

# yarn
yarn add @groundstate/cloudflare

# pnpm
pnpm add @groundstate/cloudflare

Quick Start

// src/index.ts (Cloudflare Worker)
import { GroundstateDurableObject } from '@groundstate/cloudflare';

export { GroundstateDurableObject };

export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);
    const roomId = url.pathname.split('/')[2]; // e.g., /room/abc

    const id = env.GROUNDSTATE.idFromName(roomId);
    const stub = env.GROUNDSTATE.get(id);
    return stub.fetch(request);
  },
};

# wrangler.toml
[durable_objects]
bindings = [{ name = "GROUNDSTATE", class_name = "GroundstateDurableObject" }]

[[migrations]]
tag = "v1"
new_classes = ["GroundstateDurableObject"]

API Highlights

Durable Object

• GroundstateDurableObject -- A Durable Object class that handles WebSocket connections, CRDT merging, and persistent storage automatically. Each instance represents one collaborative room or document.

Transport

• CloudflareTransport -- Client-side transport that connects to a Groundstate Durable Object endpoint. Use this on the client with SyncEngine:

import { SyncEngine } from '@groundstate/sync';
import { CloudflareTransport } from '@groundstate/cloudflare';

const engine = new SyncEngine(doc, new CloudflareTransport('https://my-worker.example.com/room/abc'));

Storage

• CloudflareStorageAdapter -- Storage adapter backed by Durable Object transactional storage for persistence within the Durable Object lifecycle.

Documentation

See the full documentation for complete API reference.

License

MIT