Initial commit

Author: patricktrack

.eslintrc.cjs

@@ -0,0 +1,14 @@
+module.exports = {
+	env: { browser: true, es2020: true },
+	extends: [
+		'eslint:recommended',
+		'plugin:@typescript-eslint/recommended',
+		'plugin:react-hooks/recommended',
+	],
+	parser: '@typescript-eslint/parser',
+	parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+	plugins: ['react-refresh'],
+	rules: {
+		'react-refresh/only-export-components': 'warn',
+	},
+}

.gitignore

@@ -0,0 +1,5 @@
+/*/node_modules
+node_modules
+.yarn/
+.wrangler/
+dist/

LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 tldraw Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,130 @@
+# tldraw sync server
+
+This is a production-ready backend for [tldraw sync](https://tldraw.dev/docs/sync).
+
+- Your client-side tldraw-based app can be served from anywhere you want.
+- This backend uses [Cloudflare Workers](https://developers.cloudflare.com/workers/), and will need
+  to be deployed to your own Cloudflare account.
+- Each whiteboard is synced via
+  [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) to a [Cloudflare
+  Durable Object](https://developers.cloudflare.com/durable-objects/).
+- Whiteboards and any uploaded images/videos are stored in a [Cloudflare
+  R2](https://developers.cloudflare.com/r2/) bucket.
+- Although unreliated to tldraw sync, this server also includes a component to fetch link previews
+  for URLs added to the canvas.
+  This is a minimal setup of the same system that powers multiplayer collaboration for hundreds of
+  thousands of rooms & users on www.tldraw.com. Because durable objects effectively create a mini
+  server instance for every single active room, we've never needed to worry about scale. Cloudflare
+  handles the tricky infrastructure work of ensuring there's only ever one instance of each room, and
+  making sure that every user gets connected to that instance. We've found that with this approach,
+  each room is able to handle about 30 simultaneous collaborators.
+
+## Overview
+
+[![architecture](./arch.png)](https://www.tldraw.com/ro/Yb_QHJFP9syPZq1YrV3YR?v=-255,-148,2025,1265&p=page)
+
+When a user opens a room, they connect via Workers to a durable object. Each durable object is like
+its own miniature server. There's only ever one for each room, and all the users of that room
+connect to it. When a user makes a change to the drawing, it's sent via a websocket connection to
+the durable object for that room. The durable object applies the change to its in-memory copy of the
+document, and broadcasts the change via websockets to all other connected clients. On a regular
+schedule, the durable object persists its contents to an R2 bucket. When the last client leaves the
+room, the durable object will shut down.
+
+Static assets like images and videos are too big to be synced via websockets and a durable object.
+Instead, they're uploaded to workers which store them in the same R2 bucket as the rooms. When
+they're downloaded, they're cached on cloudflare's edge network to reduce costs and make serving
+them faster.
+
+## Development
+
+To install dependencies, run `yarn`. To start a local development server, run `yarn dev`. This will
+start a [`vite`](https://vitejs.dev/) dev server for the frontend of your application, and a
+[`wrangler`](https://developers.cloudflare.com/workers/wrangler/) dev server for your workers
+backend. The app should now be running at http://localhost:5137 (and the server at
+http://localhost:5172).
+
+The backend worker is under [`worker`](./worker/), and is split across several files:
+
+- **[`worker/worker.ts`](./worker/worker.ts):** the main entrypoint to the worker, defining each
+  route available.
+- **[`worker/TldrawDurableObject.ts`](./worker/TldrawDurableObject.ts):** the sync durable object.
+  An instance of this is created for every active room. This exposes a
+  [`TLSocketRoom`](https://tldraw.dev/reference/sync-core/TLSocketRoom) over websockets, and
+  periodically saves room data to R2.
+- **[`worker/assetUploads.ts`](./worker/assetUploads.ts):** uploads, downloads, and caching for
+  static assets like images and videos.
+- **[`worker/bookmarkUnfurling.ts`](./worker/bookmarkUnfurling.ts):** extract URL metadata for bookmark shapes.
+
+The frontend client is under [`client`](./client):
+
+- **[`client/App.tsx`](./client/App.tsx):** the main client `<App />` component. This connects our
+  sync backend to the `<Tldraw />` component, wiring in assets and bookmark previews.
+- **[`client/multiplayerAssetStore.tsx`](./client/multiplayerAssetStore.tsx):** how does the client
+  upload and retrieve assets like images & videos from the worker?
+- **[`client/getBookmarkPreview.tsx`](./client/getBookmarkPreview.tsx):** how does the client fetch
+  bookmark previews from the worker?
+
+  ## Custom shapes
+
+To add support for custom shapes, see the [tldraw sync custom shapes
+docs](https://tldraw.dev/docs/sync#Custom-shapes--bindings).
+
+## Adding cloudflare to your own repo
+
+If you already have an app using tldraw and want to use the system in this repo, you can copy and
+paste the relevant parts to your own app.
+
+To point your existing client at the server defined in this repo, copy
+[`client/multiplayerAssetStore.tsx`](./client/multiplayerAssetStore.tsx) and
+[`client/getBookmarkPreview.tsx`](./client/getBookmarkPreview.tsx) into your app. Then, adapt the
+code from [`client/App.tsx`](./client/App.tsx) to your own app. When you call `useSync`, you'll need
+to pass it a URL. In development, that's `http://localhost:5172/connect/some-room-id`. We use an
+environment variable set in [`./vite.config.ts`](./vite.config.ts) to set the server URL.
+
+To add the server to your own app, copy the contents of the [`worker`](./worker/) folder and
+[`./wrangler.toml`](./wrangler.toml) into your app. Add the dependencies from
+[`package.json`](./package.json). If you're using TypeScript, you'll also need to adapt
+`tsconfig.worker.json` for your own project. You can run the worker using `wrangler dev` in the same
+folder as `./wrangler.toml`.
+
+## Deployment
+
+To deploy this example, you'll need to create a cloudflare account and create an R2 bucket to store
+your data. Update `bucket_name = 'tldraw-content'` in [`wrangler.toml`](./wrangler.toml) with the
+name of your new bucket.
+
+Run `wrangler deploy` to deploy your backend. This should give you a workers.dev URL, but you can
+also [configure a custom
+domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/).
+
+Finally, deploy your client HTML & JavaScript. Create a production build with
+`TLDRAW_WORKER_URL=https://your.workers.domain.com yarn build`. Publish the resulting build (in
+`dist/`) on a host of your choosing - we use [Vercel](https://vercel.com).
+
+When you visit your published client, it should connect to your cloudflare workers domain and sync
+your document across devices.
+
+## License
+
+This project is provided under the MIT license found [here](https://github.com/tldraw/tldraw-sync-cloudflare/blob/main/LICENSE.md). The tldraw SDK is provided under the [tldraw license](https://github.com/tldraw/tldraw/blob/main/LICENSE.md).
+
+## Trademarks
+
+Copyright (c) 2024-present tldraw Inc. The tldraw name and logo are trademarks of tldraw. Please see our [trademark guidelines](https://github.com/tldraw/tldraw/blob/main/TRADEMARKS.md) for info on acceptable usage.
+
+## Distributions
+
+You can find tldraw on npm [here](https://www.npmjs.com/package/@tldraw/tldraw?activeTab=versions).
+
+## Contribution
+
+Please see our [contributing guide](https://github.com/tldraw/tldraw/blob/main/CONTRIBUTING.md). Found a bug? Please [submit an issue](https://github.com/tldraw/tldraw/issues/new).
+
+## Community
+
+Have questions, comments or feedback? [Join our discord](https://discord.gg/rhsyWMUJxd) or [start a discussion](https://github.com/tldraw/tldraw/discussions/new). For the latest news and release notes, visit [tldraw.dev](https://tldraw.dev).
+
+## Contact
+
+Find us on Twitter/X at [@tldraw](https://twitter.com/tldraw).

arch.png

@@ -0,0 +1,36 @@
+import { useSync } from '@tldraw/sync'
+import { Tldraw } from 'tldraw'
+import { getBookmarkPreview } from './getBookmarkPreview'
+import { multiplayerAssetStore } from './multiplayerAssetStore'
+
+// Where is our worker located? Configure this in `vite.config.ts`
+const WORKER_URL = process.env.TLDRAW_WORKER_URL
+
+// In this example, the room ID is hard-coded. You can set this however you like though.
+const roomId = 'test-room'
+
+function App() {
+	// Create a store connected to multiplayer.
+	const store = useSync({
+		// We need to know the websockets URI...
+		uri: `${WORKER_URL}/connect/${roomId}`,
+		// ...and how to handle static assets like images & videos
+		assets: multiplayerAssetStore,
+	})
+
+	return (
+		<div style={{ position: 'fixed', inset: 0 }}>
+			<Tldraw
+				// we can pass the connected store into the Tldraw component which will handle
+				// loading states & enable multiplayer UX like cursors & a presence menu
+				store={store}
+				onMount={(editor) => {
+					// when the editor is ready, we need to register our bookmark unfurling service
+					editor.registerExternalAssetHandler('url', getBookmarkPreview)
+				}}
+			/>
+		</div>
+	)
+}
+
+export default App

client/App.tsx

@@ -0,0 +1,37 @@
+import { AssetRecordType, TLAsset, TLBookmarkAsset, getHashForString } from 'tldraw'
+
+// How does our server handle bookmark unfurling?
+export async function getBookmarkPreview({ url }: { url: string }): Promise<TLAsset> {
+	// we start with an empty asset record
+	const asset: TLBookmarkAsset = {
+		id: AssetRecordType.createId(getHashForString(url)),
+		typeName: 'asset',
+		type: 'bookmark',
+		meta: {},
+		props: {
+			src: url,
+			description: '',
+			image: '',
+			favicon: '',
+			title: '',
+		},
+	}
+
+	try {
+		// try to fetch the preview data from the server
+		const response = await fetch(
+			`${process.env.TLDRAW_WORKER_URL}/unfurl?url=${encodeURIComponent(url)}`
+		)
+		const data = await response.json()
+
+		// fill in our asset with whatever info we found
+		asset.props.description = data?.description ?? ''
+		asset.props.image = data?.image ?? ''
+		asset.props.favicon = data?.favicon ?? ''
+		asset.props.title = data?.title ?? ''
+	} catch (e) {
+		console.error(e)
+	}
+
+	return asset
+}

client/getBookmarkPreview.tsx

@@ -0,0 +1,7 @@
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@500;700@400;700&display=swap');
+@import url('tldraw/tldraw.css');
+
+body {
+	font-family: 'Inter', sans-serif;
+	overscroll-behavior: none;
+}

client/index.css

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.tsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
+	<React.StrictMode>
+		<App />
+	</React.StrictMode>
+)

client/main.tsx

@@ -0,0 +1,33 @@
+import { TLAssetStore, uniqueId } from 'tldraw'
+
+const WORKER_URL = process.env.TLDRAW_WORKER_URL
+
+// How does our server handle assets like images and videos?
+export const multiplayerAssetStore: TLAssetStore = {
+	// to upload an asset, we...
+	async upload(_asset, file) {
+		// ...create a unique name & URL...
+		const id = uniqueId()
+		const objectName = `${id}-${file.name}`.replace(/[^a-zA-Z0-9.]/g, '-')
+		const url = `${WORKER_URL}/uploads/${objectName}`
+
+		// ...POST it to out worker to upload it...
+		const response = await fetch(url, {
+			method: 'POST',
+			body: file,
+		})
+
+		if (!response.ok) {
+			throw new Error(`Failed to upload asset: ${response.statusText}`)
+		}
+
+		// ...and return the URL to be stored with the asset record.
+		return url
+	},
+
+	// to retrieve an asset, we can just use the same URL. you could customize this to add extra
+	// auth, or to serve optimized versions / sizes of the asset.
+	resolve(asset) {
+		return asset.props.src
+	},
+}