add sync-wasm-vite example

2025-12-26 12:34:22 +01:00 · 2025-10-03 14:43:23 +04:00
parent d4373379cd
commit 82d53f8d06
8 changed files with 1439 additions and 0 deletions
--- a/bindings/javascript/examples/sync-wasm-vite/.gitignore
+++ b/bindings/javascript/examples/sync-wasm-vite/.gitignore
@@ -0,0 +1 @@
+.vercel
--- a/bindings/javascript/examples/sync-wasm-vite/README.md
+++ b/bindings/javascript/examples/sync-wasm-vite/README.md
@@ -0,0 +1,84 @@
+# sync-wasm-vite
+
+This is a minimal example showing how to use [`@tursodatabase/sync-wasm`](https://www.npmjs.com/package/@tursodatabase/sync-wasm) in the browser with [Vite](https://vite.dev/).  
+
+The `@tursodatabase/sync-wasm` package extends a regular database with **bidirectional synchronization** between a local file and a remote [Turso Cloud](https://turso.tech/) database.
+
+It allows you to:
+
+* **`pull()`**: fetch and apply remote changes into your local database.
+  This ensures your local state reflects the latest server-side updates.
+
+* **`push()`**: upload local changes back to the remote database.
+  This is useful when you’ve made inserts/updates locally and want to replicate them to the cloud.
+
+Together, these methods make it possible to work **offline-first** (mutating the local database) and later sync your changes to Turso Cloud, while also bringing in any updates from other clients.
+
+---
+
+## Usage
+
+```bash
+npm install
+
+export VITE_TURSO_AUTH_TOKEN=$(turso db tokens create <db-name>) # create auth token for the database in the Turso Cloud
+export VITE_TURSO_DATABASE_URL=$(turso db show <db-name> --url) # fetch URL for the database in the Turso Cloud
+
+npm run dev
+# or build assets and serve them with simple node.js server
+npm run build
+npm run serve
+```
+
+> **⚠️ Warning:** When using `VITE_TURSO_AUTH_TOKEN` in the browser, **this token will be bundled into your client-side code**.  
+That means it is **publicly visible to anyone** who loads your site.
+> - Do **not** treat this token as a secret.  
+> - Only use it with databases or roles that are safe to expose (e.g., read-only, demo instances).
+
+---
+
+## Important: COOP / COEP Headers
+
+Because `@tursodatabase/database-wasm` relies on **SharedArrayBuffer**, you need Cross-Origin headers in development and production:
+
+### Vite dev server config (`vite.config.js`)
+
+```js
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  server: {
+    headers: {
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    }
+  }
+})
+```
+
+### Static production server (`server.mjs`)
+
+When serving the `dist/` build, also make sure your server sets these headers:
+
+```js
+res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+```
+
+### Vercel deployment
+
+If you deploy to [**Vercel**](https://vercel.com/), add a `vercel.json` file to ensure COOP / COEP headers are set:
+
+```json
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
+        { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }
+      ]
+    }
+  ]
+}
+```
--- a/bindings/javascript/examples/sync-wasm-vite/index.html
+++ b/bindings/javascript/examples/sync-wasm-vite/index.html
@@ -0,0 +1,128 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <title>Guestbook</title>
+  <style>
+    body {
+      font-family: sans-serif;
+      max-width: 600px;
+      margin: 2rem auto;
+    }
+
+    #comments {
+      border: 1px solid #ddd;
+      border-radius: 6px;
+      padding: 0;
+      list-style: none;
+    }
+
+    #comments li {
+      padding: 8px;
+      border-top: 1px solid #eee;
+    }
+
+    #comments li:first-child {
+      border-top: none;
+    }
+
+    .time {
+      font-size: 0.8em;
+      color: gray;
+    }
+  </style>
+</head>
+
+<body>
+  <h1>Guestbook</h1>
+  <form id="form">
+    <input id="comment" placeholder="Write a comment..." style="width:70%; padding:6px;" />
+    <button type="submit">Add</button>
+  </form>
+  <ul id="comments"></ul>
+
+  <script type="module">
+    import { connect } from "@tursodatabase/sync-wasm/vite";
+
+    console.info(import.meta.env.VITE_TURSO_AUTH_TOKEN);
+    console.info(import.meta.env.VITE_TURSO_DATABASE_URL);
+    let db = await connect({
+      path: "sync-guestbook.db", // local path to store database
+      authToken: import.meta.env.VITE_TURSO_AUTH_TOKEN, // Turso Cloud auth token, WARNING: Bundled into browser code, so it is NOT secret. Use carefully.
+      url: import.meta.env.VITE_TURSO_DATABASE_URL, // Turso Cloud database url
+      longPollTimeoutMs: 5000, // optional long-polling interval for pull operation; useful in case when pull called in a loop
+    });
+    // execute multiple SQL statements with exec(...)
+    await db.exec(`
+      CREATE TABLE IF NOT EXISTS guestbook ( comment TEXT, created_at DEFAULT (unixepoch()) );
+      CREATE INDEX IF NOT EXISTS guestbook_idx ON guestbook (created_at);
+    `);
+    await refresh();
+
+    async function pull() {
+      try {
+        // pull new data from remote
+        await db.pull();
+        await refresh();
+      } catch (e) {
+        console.error('pull error', e);
+      } finally {
+        setTimeout(pull, 0);
+      }
+    }
+    async function push() {
+      try {
+        // if there is something new for push
+        if ((await db.stats()).operations > 0) {
+          // push new data to remote
+          await db.push();
+        }
+      } catch (e) {
+        console.error('push error', e);
+      } finally {
+        setTimeout(push, 10);
+      }
+    }
+
+    pull();
+    push();
+
+    async function addComment() {
+      // use prepared statements and bind args to placeholders later
+      const insert = db.prepare(`INSERT INTO guestbook(comment) VALUES (?)`);
+
+      const input = document.getElementById("comment");
+      const text = input.value.trim();
+      input.value = "";
+
+      // use run(...) method if query only need to be executed till completion
+      await insert.run([text]);
+
+      await refresh();
+    }
+    document.getElementById("form").addEventListener("submit", (e) => {
+      e.preventDefault();
+      addComment();
+    });
+
+    async function refresh() {
+      const select = db.prepare(`SELECT comment, created_at FROM guestbook ORDER BY created_at DESC LIMIT ?`);
+      // use all(...) or get(...) methods to get all or one row from the query
+      const rows = await select.all([5]);
+
+      const ul = document.getElementById("comments");
+      ul.innerHTML = "";
+      rows.forEach((row) => {
+        const li = document.createElement("li");
+        li.innerHTML = `
+              <div>${row.comment}</div>
+              <div class="time">${new Date(row.created_at * 1000).toLocaleString()}</div>
+            `;
+        ul.appendChild(li);
+      });
+    }
+  </script>
+</body>
+
+</html>
--- a/bindings/javascript/examples/sync-wasm-vite/package-lock.json
+++ b/bindings/javascript/examples/sync-wasm-vite/package-lock.json
--- a/bindings/javascript/examples/sync-wasm-vite/package.json
+++ b/bindings/javascript/examples/sync-wasm-vite/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "sync-wasm-vite",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "serve": "node server.mjs"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "vite": "^7.1.9"
+  },
+  "dependencies": {
+    "@tursodatabase/sync-wasm": "^0.2.0"
+  }
+}
--- a/bindings/javascript/examples/sync-wasm-vite/server.mjs
+++ b/bindings/javascript/examples/sync-wasm-vite/server.mjs
@@ -0,0 +1,34 @@
+import http from "http";
+import { readFile } from "fs/promises";
+import { extname, join } from "path";
+import { fileURLToPath } from "url";
+
+const root = fileURLToPath(new URL("./dist", import.meta.url));
+const port = 8080;
+
+const mimeTypes = { ".html": "text/html", ".js": "application/javascript" };
+
+const server = http.createServer(async (req, res) => {
+  // COOP / COEP headers necessary for shared WASM memory
+  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+  res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+
+  try {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const pathname = url.pathname;
+    const filePath = pathname === "/" ? "index.html" : pathname;
+    const fullPath = join(root, filePath);
+
+    const data = await readFile(fullPath);
+    const ext = extname(fullPath).toLowerCase();
+    const contentType = mimeTypes[ext] || "application/octet-stream";
+
+    res.writeHead(200, { "Content-Type": contentType });
+    res.end(data);
+  } catch (err) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not found");
+  }
+});
+
+server.listen(port, "0.0.0.0", () => console.log(`Serving on http://localhost:${port}`));
--- a/bindings/javascript/examples/sync-wasm-vite/vercel.json
+++ b/bindings/javascript/examples/sync-wasm-vite/vercel.json
@@ -0,0 +1,11 @@
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
+        { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }
+      ]
+    }
+  ]
+}
--- a/bindings/javascript/examples/sync-wasm-vite/vite.config.ts
+++ b/bindings/javascript/examples/sync-wasm-vite/vite.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  server: {
+    headers: {
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    }
+  }
+})