@livestore/livestore 0.4.0-dev.21 → 0.4.0-dev.23

package/docs/tutorial/4-sync-data-via-cloudflare/index.md

@@ -1,210 +0,0 @@
-# 4. Sync data to Cloudflare
-
-In this step, you're going to introduce a [sync](/building-with-livestore/syncing) backend. This sync backend will:
-
-- Have a "live connection" (via WebSockets) to _all_ the clients that are running your app.
-- Propagate events to _all_ other clients whenever a particular client emits an event.
-
-Notice how you'll achieve this by _only_ changing the data layer of your application! 
-
-You won't need to touch the code that you've already written in `main.tsx` and `App.tsx`—all the syncing is handled by LiveStore under the hood without you needing to worry about it in your application code.
-
-You're going to implement the sync backend using [Cloudflare Workers](https://developers.cloudflare.com/workers/) and [Durable Objects](https://developers.cloudflare.com/durable-objects/), using the [@livestore/sync-cf](/sync-providers/cloudflare) package.
-
-## Install the Cloudflare sync provider package
-
-Run the following command in your terminal:
-
-<Tabs syncKey="package-manager">
-
-  <TabItem label="bun">
-
-    <Code code={`bun add @livestore/sync-cf@0.4.0-dev.14`} lang="sh" />
-
-  </TabItem>
-
-  <TabItem label="pnpm">
-
-    <Code code={`pnpm add @livestore/sync-cf@0.4.0-dev.14`} lang="sh" />
-
-  </TabItem>
-
-</Tabs>
-
-## Create the sync backend
-
-Now, create a new `sync` directory and a new file for the sync backend:
-
-```bash
-mkdir src/sync
-touch src/sync/client-ws.ts
-```
-
-Now, add the following code to it:
-
-```ts title="src/sync/client-ws.ts"
-
-export class SyncBackendDO extends makeDurableObject({
-  onPush: async (message, context) => {
-    console.log('client-ws.ts: onPush', message, context)
-  },
-  onPull: async (message, context) => {
-    console.log('client-ws.ts: onPull', message, context)
-  },
-}) {}
-
-export default {
-  async fetch(request: CfTypes.Request, _env: SyncBackend.Env, ctx: CfTypes.ExecutionContext) {
-    const searchParams = SyncBackend.matchSyncRequest(request)
-    console.log('client-ws.ts: fetch in  with searchParams', searchParams)
-    if (searchParams !== undefined) {
-      return SyncBackend.handleSyncRequest({
-        request,
-        searchParams,
-        ctx,
-        syncBackendBinding: 'SYNC_BACKEND_DO',
-      })
-    }
-
-    return new Response('Not Found', { status: 404 })
-  },
-}
-```
-
-This code will be deployed as a Durable Object (think of it as a "Cloudflare Worker with WebSocket capabilities and attached storage").
-
-In this tutorial, you won't need to go beyond the following basic boilerplate code for syncing. 
-
-However, in more advanced scenarios, there are ways for you to hook into the connection between your client apps and the sync backend. This could e.g. be useful when your app requires authentication and you need to send along an auth token.
-
-Next, you need to slightly modify the code for your LiveStore web worker in `/src/livestore/livestore.worker.ts`:
-
-```diff title="/src/livestore/livestore.worker.ts" lang="ts"
-
-+import { makeWsSync } from '@livestore/sync-cf/client'
-
-makeWorker({ 
-  schema,
-+  sync: {
-+    backend: makeWsSync({ url: `${location.origin}/sync` }),
-+  }
-})
-```
-
-Finally, you need to update your `wrangler.toml` to ensure Vite and Cloudflare know about the new sync backend:
-
-```diff title="wrangler.toml" lang="toml"
-name = "livestore-todo-app"
-compatibility_date = "2024-10-28"
-+main = "./src/sync/client-ws.ts"
-+compatibility_flags = [
-+  "nodejs_compat",
-+]
-
-[observability]
-enabled = true
-
-+[[durable_objects.bindings]]
-+name = "SYNC_BACKEND_DO"
-+class_name = "SyncBackendDO"
-
-+[[migrations]]
-+tag = "v1"
-+new_sqlite_classes = ["SyncBackendDO"]
-```
-
-Here's a quick rundown of the changes:
-
-- `main`: Since you're now introducing a "backend", your app needs to be reconfigured. It now has a dedicated entry point in `./src/sync/client-ws.ts`. When your Worker receives a request, this file's exported handlers are executed. In your case, it points to the WebSocket sync backend implementation.
-- `durable_objects.bindings`: This configures the bindings for your Durable Object. You'll be able to inspect it in the Cloudflare Dashboard by its name `SYNC_BACKEND_DO`.
-- `migrations`: Whenever you introduce a new Durable Object that supports [SQLite storage](https://developers.cloudflare.com/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class) (or update an existing one), you need to add a migration referencing the new or updated Durable Object class. 
-
-You're now ready to run and deploy the app:
-
-<Tabs syncKey="package-manager">
-
-  <TabItem label="bun">
-
-    <Code code={`bun run deploy`} lang="sh" />
-
-  </TabItem>
-
-  <TabItem label="pnpm">
-
-    <Code code={`pnpm run deploy`} lang="sh" />
-
-  </TabItem>
-
-</Tabs>
-
-<details>
-<summary>Expand to view the expected output</summary>
-
-```
-✗ pnpm run deploy
-
-> livestore-todo-app@0.0.0 deploy /Users/nikolasburk/Projects/LiveStore/plain-react-tutorial/livestore-todo-app
-> pnpm run build && wrangler deploy
-
-> livestore-todo-app@0.0.0 build /Users/nikolasburk/Projects/LiveStore/plain-react-tutorial/livestore-todo-app
-> tsc -b && vite build
-
-vite v7.1.12 building SSR bundle for production...
-✓ 1085 modules transformed.
-dist/livestore_todo_app/.vite/manifest.json      0.16 kB
-dist/livestore_todo_app/wrangler.json            1.37 kB
-dist/livestore_todo_app/index.js             1,021.14 kB
-✓ built in 1.31s
-vite v7.1.12 building for production...
-✓ 1119 modules transformed.
-dist/client/index.html                               0.47 kB │ gzip:   0.30 kB
-dist/client/assets/make-shared-worker-CbM93UVL.js  363.01 kB
-dist/client/assets/livestore.worker-DbNV_so_.js    594.87 kB
-dist/client/assets/wa-sqlite-CLgeTS2u.wasm         618.93 kB │ gzip: 303.78 kB
-dist/client/assets/index-DNxhg8nM.css               11.76 kB │ gzip:   3.12 kB
-dist/client/assets/index-BhsI_Uw7.js               760.04 kB │ gzip: 238.67 kB
-
-(!) Some chunks are larger than 500 kB after minification. Consider:
-- Using dynamic import() to code-split the application
-- Use build.rollupOptions.output.manualChunks to improve chunking: https://rollupjs.org/configuration-options/#output-manualchunks
-- Adjust chunk size limit for this warning via build.chunkSizeWarningLimit.
-✓ built in 4.29s
-
- ⛅️ wrangler 4.45.1
-───────────────────
-Using redirected Wrangler configuration.
- - Configuration being used: "dist/livestore_todo_app/wrangler.json"
- - Original user's configuration: "wrangler.toml"
- - Deploy configuration file: ".wrangler/deploy/config.json"
-🌀 Building list of assets...
-✨ Read 8 files from the assets directory /Users/nikolasburk/Projects/LiveStore/plain-react-tutorial/livestore-todo-app/dist/client
-🌀 Starting asset upload...
-🌀 Found 4 new or modified static assets to upload. Proceeding with upload...
-+ /index.html
-+ /assets/index-BhsI_Uw7.js
-+ /assets/index-DNxhg8nM.css
-+ /assets/livestore.worker-DbNV_so_.js
-Uploaded 1 of 4 assets
-Uploaded 2 of 4 assets
-Uploaded 4 of 4 assets
-✨ Success! Uploaded 4 files (3 already uploaded) (4.31 sec)
-
-Total Upload: 997.21 KiB / gzip: 208.73 KiB
-Worker Startup Time: 47 ms
-Your Worker has access to the following bindings:
-Binding                                  Resource            
-env.SYNC_BACKEND_DO (SyncBackendDO)      Durable Object      
-
-Uploaded livestore-todo-app (17.72 sec)
-Deployed livestore-todo-app triggers (9.82 sec)
-  https://livestore-todo-app.nikolas-burk.workers.dev
-Current Version ID: 8860dd68-6082-4da9-9407-dea670cd8b23
-```
-
-</details>
-
-Feel free to test the new behaviour locally or using the deployed version. This time, data syncing will work across browsers and even devices!
-
-Here's a GIF demonstrating how a regular Chrome tab, an incognito Chrome tab and a Safari tab are staying in sync automatically:
-
-![](../../../assets/tutorial/chapter-4/1-livestore-cf-sync.gif)

package/docs/tutorial/5-expand-business-logic/index.md

@@ -1,174 +0,0 @@
-# 5. Expand business logic with more events
-
-In this chapter, you'll expand the business logic of the app by adding a "todo completed" feature.
-
-You'll do this in these steps:
-
-1. Update your schema to:
-    1. Add a `boolean` column to your SQLite table.
-    2. Add events to mark a todo as completed and uncompleted.
-    3. Add a materializer to update the DB when one of these events happens.
-2. Update the UI with a checkbox element for each todo which sends these events when toggled.
-
-## Update your LiveStore schema
-
-Open your `schema.ts` file and update it with a new column, and two events (for completing and uncompleting a todo) with two corresponding materializers:
-
-```diff title="src/livestore/schema.ts" lang="ts"
-
-export const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.integer({ primaryKey: true }),
-      text: State.SQLite.text({ default: '' }),
-+      completed: State.SQLite.boolean({ default: false }),
-    },
-  })
-}
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.Number, text: Schema.String }),
-  }),
-  todoDeleted: Events.synced({
-    name: 'v1.TodoDeleted',
-    schema: Schema.Struct({ id: Schema.Number }),
-  }),
-+  todoCompleted: Events.synced({
-+    name: 'v1.TodoCompleted',
-+    schema: Schema.Struct({ id: Schema.Number }),
-+  }),
-+  todoUncompleted: Events.synced({
-+    name: 'v1.TodoUncompleted',
-+    schema: Schema.Struct({ id: Schema.Number }),
-+  }),
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text }),
-  'v1.TodoDeleted': ({ id }) => tables.todos.delete().where({ id: id }),
-
-+  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
-+  'v1.TodoUncompleted': ({ id }) => tables.todos.update({ completed: false }).where({ id }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-export const schema = makeSchema({ events, state })
-```
-
-## Update the UI and business logic
-
-Next, add a `toggleTodo` function in `App.tsx` in which you're emitting the events that you've just defined and invoke it from a new checkbox element that's added to each todo element:
-
-```diff title="src/App.tsx" lang="ts"
-
-function App() {
-
-  const { store } = useStore()
-
-  const todos$ = queryDb(() => tables.todos.select())
-
-  const todos = store.useQuery(todos$)
-
-  const [input, setInput] = useState('')
-
-  const addTodo = () => {
-    if (input.trim()) {
-      store.commit(
-        events.todoCreated({ id: Date.now(), text: input }),
-      )
-      setInput('')
-    }
-  }
-
-  const deleteTodo = (id: number) => {
-    store.commit(
-      events.todoDeleted({ id }),
-    )
-  }
-
-+  const toggleTodo = (id: number, completed: boolean) => {
-+    store.commit(
-+      completed ? events.todoUncompleted({ id }) : events.todoCompleted({ id })
-+    )
-+  }
-
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key === 'Enter') {
-      addTodo()
-    }
-  }
-
-  return (
-    <div className="min-h-screen bg-gray-50 flex items-center justify-center p-6">
-      <div className="w-full max-w-lg">
-        <h1 className="text-5xl font-bold text-gray-800 text-center mb-12">
-          Todo List
-        </h1>
-
-        <div className="flex gap-3 mb-8">
-          <input
-            type="text"
-            value={input}
-            onChange={(e) => setInput(e.target.value)}
-            onKeyDown={handleKeyDown}
-            placeholder="Enter a todo..."
-            className="flex-1 px-4 py-2 text-sm border border-gray-300 rounded focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
-          />
-          <button
-            onClick={addTodo}
-            className="px-6 py-2 text-sm font-medium text-white bg-blue-500 rounded hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 transition-colors"
-          >
-            Add
-          </button>
-        </div>
-
-        <div className="space-y-3">
-          {todos.map(todo => (
-+            <div
-+            key={todo.id}
-+            className="flex items-center justify-between bg-white px-4 py-3 rounded shadow-sm"
-+          >
-+            <div className="flex items-center gap-3 flex-1">
-+              <input
-+                type="checkbox"
-+                checked={todo.completed}
-+                onChange={() => toggleTodo(todo.id, todo.completed)}
-+                className="w-4 h-4 cursor-pointer"
-+              />
-+              <span className={`text-gray-700 ${todo.completed ? 'line-through text-gray-400' : ''}`}>
-+                {todo.text}
-+              </span>
-+            </div>
-+            <button
-+              onClick={() => deleteTodo(todo.id)}
-+              className="px-4 py-1 text-sm font-medium text-white bg-red-500 rounded hover:bg-red-600 focus:outline-none focus:ring-2 focus:ring-red-500 focus:ring-offset-2 transition-colors"
-+            >
-+              Delete
-+            </button>
-+          </div>
-          ))}
-        </div>
-
-        {todos.length === 0 && (
-          <p className="text-center text-gray-400 mt-8">
-            No todos yet. Add one above!
-          </p>
-        )}
-      </div>
-    </div>
-  )
-}
-
-export default App
-```
-
-## Deploy and test
-
-If you run or deploy the app, the UI will now look as follows:
-
-![](../../../assets/tutorial/chapter-5/0-completed-ui.png)
-
-Because the `completed` field is also being persisted in the database, it also auto-syncs across browser sessions and devices.