@kazzle/app 0.1.693

package/templates/realtime-app/components/server/deploy.ts

@@ -0,0 +1,105 @@
+/**
+ * Boot-time deploy step for the server component.
+ *
+ * Two jobs, both idempotent:
+ *
+ *   1. Apply pending SQL migrations from `migrations/` so the database schema
+ *      is up-to-date before the HTTP server starts taking traffic. Migration
+ *      failure is FATAL — we'd rather crash than serve traffic against a
+ *      half-migrated database.
+ *   2. Tell the sync service which tables to replicate to clients. We do this
+ *      from inside the app — not from a deploy pipeline — so a new table
+ *      becomes syncable the moment its migration lands. There's no separate
+ *      "sync config" file to keep in sync with the schema. Sync rules push
+ *      failure is NON-FATAL: the app still boots and serves HTTP, sync just
+ *      doesn't pick up schema changes from this boot. The platform retries.
+ *
+ * The whole function is safe to re-run on every process start. Migrations
+ * track their own state in `migrations.applied` (created by 001_init); the
+ * sync rules deploy replaces the existing rule set atomically.
+ */
+
+import postgres from 'postgres';
+import { readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export async function deploy() {
+  // Use the direct (non-pooled) connection string. Migrations may run DDL
+  // that PgBouncer's transaction pooling can't handle, and the connection is
+  // closed immediately afterwards so we don't need pooling here anyway.
+  const sql = postgres(process.env.DIRECT_DATABASE_URL!);
+
+  // ─── 1. Migrations ───────────────────────────────────────────────────────
+  // Convention: numbered `.sql` files in `migrations/`, sorted lexically.
+  // Each file is one transaction. To add a migration: create
+  // `migrations/002_<description>.sql` and ship — it will run on next boot.
+  const migrationsDir = join(import.meta.dir, 'migrations');
+  if (existsSync(migrationsDir)) {
+    const files = readdirSync(migrationsDir).filter(f => f.endsWith('.sql')).sort();
+    for (const file of files) {
+      const content = await Bun.file(join(migrationsDir, file)).text();
+      await sql.unsafe(content);
+      console.log(`[deploy] Applied migration: ${file}`);
+    }
+  }
+
+  // ─── 2. Sync rules ───────────────────────────────────────────────────────
+  // Introspect every base table in the `public` schema. The sync service is
+  // told to replicate all of them to every authenticated client.
+  //
+  // If you need fine-grained access control (e.g. each user only sees their
+  // own rows), replace the wildcard `SELECT *` below with a query that
+  // references `auth.user_id()` — the sync service evaluates that function
+  // per-connection using the JWT's `sub` claim. Example:
+  //
+  //   SELECT * FROM notes WHERE owner_id = auth.user_id()
+  const tables = await sql`
+    SELECT table_name FROM information_schema.tables
+    WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+      AND table_name NOT IN ('powersync', 'pg_stat_statements')
+  `;
+
+  if (tables.length === 0) {
+    console.log('[deploy] No tables found — skipping sync streams');
+    await sql.end();
+    return;
+  }
+
+  // Sync rules are written in YAML and posted to the sync service's admin
+  // API. "edition: 3" is the current rules format. The `auto_subscribe: true`
+  // flag means clients receive these tables without having to explicitly
+  // subscribe — appropriate for a small app with a single rule group.
+  const queries = tables.map(t => `      - SELECT * FROM ${t.table_name}`).join('\n');
+  const streamsYaml = `config:\n  edition: 3\nstreams:\n  app_data:\n    auto_subscribe: true\n    queries:\n${queries}`;
+
+  // NON-FATAL: if the sync service is unreachable (DNS, network, dead Fly
+  // app, etc.) the app still boots and serves HTTP. Sync just won't pick up
+  // schema changes from this particular boot. Holding the entire app hostage
+  // on a sync push failure means a single dead PowerSync instance makes the
+  // whole product look broken — UI shell included.
+  try {
+    const res = await fetch(`${process.env.APP_SYNC_URL}/api/sync-rules/v1/deploy`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/yaml',
+        // The admin token is a shared secret between this app and its sync
+        // service — different from the per-client JWTs minted in routes.ts.
+        'Authorization': `Bearer ${process.env.APP_SYNC_API_TOKEN}`,
+      },
+      body: streamsYaml,
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) {
+      const body = await res.text();
+      console.warn(`[deploy] Sync streams deploy failed (HTTP ${res.status}): ${body}. Continuing without re-deploying sync rules.`);
+    } else {
+      console.log('[deploy] Sync streams deployed successfully');
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`[deploy] Sync streams deploy failed: ${message}. Continuing without re-deploying sync rules.`);
+  }
+
+  await sql.end();
+}

package/templates/realtime-app/components/server/index.ts

@@ -0,0 +1,40 @@
+/**
+ * {{APP_NAME}} — server component entry point.
+ *
+ * Order matters here. We run `deploy()` to completion BEFORE starting the
+ * HTTP server so the schema is current before we accept traffic. Migrations
+ * are fatal: if they throw, the process crashes rather than serving against
+ * a half-migrated database. Sync rules push is non-fatal — see deploy.ts.
+ *
+ * `await` at the top level requires `"type": "module"` in package.json
+ * (Bun and Node both support this). The platform supervisor restarts the
+ * process if `deploy()` throws.
+ */
+
+import { deploy } from './deploy';
+import { routes } from './routes';
+
+// PORT and HOST come from the platform when running under `kazzle run`.
+// The fallback (3001 / 127.0.0.1) is only for direct `bun run index.ts`
+// invocations during local hacking.
+// ─────────────────────────────────────────────────────────────────────────
+//  DO NOT CHANGE THE NEXT 4 LINES.  DO NOT ADD FALLBACKS.  DO NOT HARDCODE.
+//  PORT and HOST are injected by `kazzle run`. Missing values must throw so
+//  the platform sees a fast, readable failure instead of binding to the
+//  wrong port.
+// ─────────────────────────────────────────────────────────────────────────
+if (!process.env.PORT || !process.env.HOST) {
+  throw new Error('PORT and HOST must be set by "kazzle run" — never hardcode them.');
+}
+const PORT = Number(process.env.PORT);
+const HOST = process.env.HOST;
+
+await deploy();
+
+const server = Bun.serve({
+  hostname: HOST,
+  port: PORT,
+  fetch: routes,
+});
+
+console.log(`[{{APP_NAME}}] Server listening on ${server.hostname}:${server.port}`);

package/templates/realtime-app/components/server/migrations/001_items.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS items (
+  id text PRIMARY KEY,
+  text text NOT NULL,
+  done integer NOT NULL DEFAULT 0,
+  created_at bigint NOT NULL
+);

package/templates/realtime-app/components/server/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{APP_SLUG}}-server",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "start": "bun run index.ts",
+    "dev": "kazzle run -- bun --watch index.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions",
+    "check": "bun run typecheck"
+  },
+  "dependencies": {
+    "hono": "^4.12.16",
+    "jose": "^6.0.11",
+    "postgres": "^3.4.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6",
+    "typescript": "^5.8.3"
+  }
+}

package/templates/realtime-app/components/server/routes.ts

@@ -0,0 +1,137 @@
+/**
+ * HTTP routes for the realtime app's server component.
+ *
+ * Two endpoints, both required by the offline-first sync engine running in the
+ * UI:
+ *
+ *   GET  /sync/token  — hands the UI a short-lived signed JWT it uses to
+ *                           open a WebSocket to the sync service.
+ *   POST /sync        — receives batched client mutations (PUT/PATCH/DELETE)
+ *                           and writes them straight into Postgres. The sync
+ *                           service then streams them back out to every other
+ *                           connected client.
+ *
+ * Everything that talks to the database goes through `postgres.js`. We use the
+ * tagged-template form (sql`...`) deliberately — see the upload handler below
+ * for why.
+ */
+
+import { importJWK, SignJWT } from 'jose';
+import postgres from 'postgres';
+
+// One module-level pool. The default settings are fine for a single Fly
+// machine; postgres.js auto-commits each query at the end of execution, which
+// is the behaviour we want for an autocommit CRUD endpoint.
+const sql = postgres(process.env.DATABASE_URL!);
+
+// The signing key is loaded lazily so a misconfigured env var doesn't crash
+// the server before it can even serve /health. The kid travels with the JWT
+// header so the sync service can pick the right verifier key from its JWKS.
+let privateKey: CryptoKey;
+let kid: string;
+
+async function getSigningKey() {
+  if (privateKey) return { privateKey, kid };
+  const jwk = JSON.parse(process.env.APP_SYNC_SIGNING_KEY!);
+  kid = jwk.kid;
+  privateKey = await importJWK(jwk, 'EdDSA') as CryptoKey;
+  return { privateKey, kid };
+}
+
+export async function routes(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+
+  // Liveness probe used by the platform supervisor. Must stay cheap and never
+  // touch the database — if the DB is briefly unreachable we still want the
+  // process to be considered "up" so the supervisor doesn't kill it.
+  if (url.pathname === '/health') {
+    return Response.json({ status: 'ok' });
+  }
+
+  // ─── Credentials endpoint ────────────────────────────────────────────────
+  //
+  // The UI's sync client calls this on boot and again whenever its token is
+  // about to expire. We mint a fresh JWT and tell the client which sync
+  // service URL to talk to.
+  //
+  // Important claims:
+  //   - alg: EdDSA matches the signing key. The sync service's JWKS entry
+  //     declares the same alg.
+  //   - sub: every JWT verified by the sync service MUST carry a `sub`
+  //     claim. The service rejects tokens without one (PSYNC_S2101).
+  //     Use a stable identifier here — even a constant is fine for
+  //     single-tenant apps; multi-tenant apps should use a real user id.
+  //   - aud: the audience is the sync service URL. The service is
+  //     configured with the same value; a mismatch means the JWT is
+  //     accepted by us and rejected by it, which manifests as an endless
+  //     reconnect loop in the browser.
+  //   - exp: keep this short. The client refreshes well before expiry, so
+  //     1h is plenty.
+  if (url.pathname === '/sync/token') {
+    const { privateKey: key, kid: k } = await getSigningKey();
+    const token = await new SignJWT({})
+      .setProtectedHeader({ alg: 'EdDSA', kid: k })
+      .setSubject('app-user')
+      .setIssuedAt()
+      .setExpirationTime('1h')
+      .setAudience(process.env.APP_SYNC_URL!)
+      .sign(key);
+
+    return Response.json({ token, endpoint: process.env.APP_SYNC_URL });
+  }
+
+  // ─── Upload endpoint ─────────────────────────────────────────────────────
+  //
+  // The UI's sync client batches every local write into a transaction and
+  // POSTs the batch here. Each entry has:
+  //   - table: the target table name
+  //   - op:    PUT | PATCH | DELETE
+  //   - id:    the row's primary key
+  //   - data:  for PUT/PATCH, the column values being set
+  //
+  // We MUST use postgres.js's tagged-template form (`sql\`...\``) for the
+  // actual SQL. The older `sql.unsafe(query, params)` API silently runs in
+  // an extended-query mode whose writes are not visible to other connections
+  // until the connection is reused — the route happily returns 200 but the
+  // row never shows up to anyone else. The tagged-template form auto-commits
+  // every query, which is what we want.
+  //
+  // The `sql(value, ...keys)` helper is context-aware: inside `INSERT INTO
+  // ... ${...}` it expands to `(col1, col2, ...) VALUES ('a', 'b', ...)`,
+  // inside `SET ${...}` it expands to `col1 = 'a', col2 = 'b'`. Same call,
+  // two meanings, both safe (values are sent as bind parameters).
+  if (req.method === 'POST' && url.pathname === '/sync') {
+    const { ops } = await req.json() as {
+      ops: Array<{ table: string; op: string; id: string; data: Record<string, unknown> }>;
+    };
+
+    for (const op of ops) {
+      if (op.op === 'PUT') {
+        // Build a single row object so the id participates in the INSERT
+        // column list. ON CONFLICT then needs to update everything *except*
+        // the primary key.
+        const row: Record<string, unknown> = { id: op.id, ...op.data };
+        const cols = Object.keys(row);
+        const updateCols = cols.filter(c => c !== 'id');
+        await (sql as unknown as (s: TemplateStringsArray, ...args: unknown[]) => Promise<unknown>)`
+          INSERT INTO ${sql(op.table)} ${sql(row, ...cols)}
+          ON CONFLICT (id) DO UPDATE SET ${sql(row, ...updateCols)}
+        `;
+      } else if (op.op === 'PATCH') {
+        const cols = Object.keys(op.data);
+        await (sql as unknown as (s: TemplateStringsArray, ...args: unknown[]) => Promise<unknown>)`
+          UPDATE ${sql(op.table)} SET ${sql(op.data, ...cols)} WHERE id = ${op.id}
+        `;
+      } else if (op.op === 'DELETE') {
+        await sql`DELETE FROM ${sql(op.table)} WHERE id = ${op.id}`;
+      }
+    }
+
+    // The sync client treats 200 as "this batch is durable, drop it from
+    // my local upload queue". If you ever need to push back (e.g. validation
+    // failed) return a non-2xx so the client retries.
+    return Response.json({ ok: true });
+  }
+
+  return new Response('Not found', { status: 404 });
+}

package/templates/realtime-app/components/server/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "types": ["bun"]
+  },
+  "include": ["*.ts"]
+}

package/templates/realtime-app/components/ui/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>{{APP_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/realtime-app/components/ui/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "kazzle-realtime-app-template",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "kazzle run -- vite",
+    "typecheck": "tsc --noEmit",
+    "build": "vite build",
+    "preview": "kazzle run -- vite preview",
+    "check": "bun run typecheck && bun run build"
+  },
+  "dependencies": {
+    "@kazzle/app": "{{KAZZLE_APP_VERSION}}",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "@powersync/react": "1.10.0",
+    "@powersync/web": "1.37.1",
+    "jose": "^6.0.11",
+    "postgres": "^3.4.5",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@tailwindcss/vite": "^4.1.0",
+    "@types/uuid": "^10.0.0",
+    "@vitejs/plugin-react": "^4.5.2",
+    "tailwindcss": "^4.1.0",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "vite-plugin-pwa": "^1.0.0",
+    "workbox-window": "^7.3.0"
+  }
+}

package/templates/realtime-app/components/ui/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="hsl(230,65%,88%)"/>
+  <text x="32" y="46" text-anchor="middle" font-family="system-ui,sans-serif" font-size="40" font-weight="600" fill="hsl(230,50%,25%)">K</text>
+</svg>

package/templates/realtime-app/components/ui/src/App.tsx

@@ -0,0 +1,77 @@
+/**
+ * Example UI component showing the read + write patterns customers should
+ * use throughout the rest of the app:
+ *
+ *   - Reads use `useQuery`. The result is reactive — when any row matched
+ *     by the query changes (locally or via a sync push from another client),
+ *     the component re-renders automatically. There's no `useEffect`, no
+ *     manual subscription, no fetch on mount.
+ *   - Writes go straight to the local DB via `db.execute`. The call resolves
+ *     as soon as the row is in local SQLite (milliseconds), and the upload
+ *     to the server happens asynchronously in the background. The UI never
+ *     waits on the network.
+ *
+ * IDs are generated client-side with `uuid()`. This is intentional: it lets
+ * the row exist locally before the server has heard about it, which is what
+ * makes offline-first work. The server upserts on the id we send.
+ */
+
+import { useQuery } from '@powersync/react';
+import { useState } from 'react';
+import { v4 as uuid } from 'uuid';
+import { db } from './lib/sync';
+
+export default function App() {
+  // The SQL is plain SQLite. Joins, aggregates, ORDER BY — anything SQLite
+  // understands is fair game. Parameters can be passed as a second argument:
+  // `useQuery('SELECT * FROM items WHERE done = ?', [0])`.
+  const { data: items } = useQuery<{ id: string; text: string; done: number }>(
+    'SELECT * FROM items ORDER BY created_at DESC',
+  );
+  const [draft, setDraft] = useState('');
+
+  const addItem = async (event: React.FormEvent) => {
+    event.preventDefault();
+    const text = draft.trim();
+    if (!text) return;
+    // INSERT writes to local SQLite. The connector's upload loop picks it
+    // up on the next tick and POSTs it to /sync.
+    await db.execute(
+      'INSERT INTO items (id, text, done, created_at) VALUES (?, ?, ?, ?)',
+      [uuid(), text, 0, Date.now()],
+    );
+    setDraft('');
+  };
+
+  const toggle = async (id: string, done: number) => {
+    await db.execute('UPDATE items SET done = ? WHERE id = ?', [done ? 0 : 1, id]);
+  };
+
+  return (
+    <div className="page">
+      <h1>{{APP_NAME}}</h1>
+      {/* `add-form` / `add-input` are stable hooks used by the template smoke
+          test; styling comes from the `.row` / `.input` / `.btn` primitives. */}
+      <form className="add-form row" onSubmit={addItem}>
+        <input
+          className="add-input input flex-1"
+          value={draft}
+          onChange={event => setDraft(event.target.value)}
+          placeholder="Add an item"
+        />
+        <button className="btn btn-primary" type="submit">Add item</button>
+      </form>
+      <ul className="stack m-0 list-none p-0">
+        {items.map(item => (
+          <li
+            key={item.id}
+            className={`item card cursor-pointer ${item.done ? 'item-done muted line-through' : ''}`}
+            onClick={() => toggle(item.id, item.done)}
+          >
+            {item.text}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/templates/realtime-app/components/ui/src/lib/connector.ts

@@ -0,0 +1,80 @@
+/**
+ * The "connector" is the bridge between the local sync engine and the app's
+ * own server. The sync engine asks the connector two questions:
+ *
+ *   1. fetchCredentials() — "what JWT and endpoint should I use to open the
+ *      sync WebSocket?" Called on first connect and again whenever the token
+ *      is close to expiring.
+ *   2. uploadData()       — "I've batched the user's pending local writes
+ *      into a transaction. Send them somewhere durable and tell me when
+ *      they're persisted."
+ *
+ * Everything else — reads, conflict resolution, retries, reconnection — is
+ * handled by the sync engine. The connector intentionally has no read path.
+ */
+
+import {
+  type AbstractPowerSyncDatabase,
+  type PowerSyncBackendConnector,
+  type CrudEntry,
+} from '@powersync/web';
+
+// Endpoint paths can be overridden at build time via Vite env vars. In dev,
+// the defaults work because `vite.config.ts` proxies `/sync*` to the server
+// component. In prod, both surfaces are served from the same origin so the
+// relative paths just work.
+const TOKEN_ENDPOINT = import.meta.env.VITE_APP_SYNC_TOKEN_ENDPOINT || '/sync/token';
+const SYNC_UPLOAD_ENDPOINT = import.meta.env.VITE_SYNC_UPLOAD_ENDPOINT || '/sync';
+
+export class AppConnector implements PowerSyncBackendConnector {
+  /**
+   * Mint a fresh JWT by asking our own server. We never store the token —
+   * the sync engine caches it internally and calls back here when it needs
+   * a new one, so refresh-on-expiry is automatic.
+   */
+  async fetchCredentials() {
+    const res = await fetch(TOKEN_ENDPOINT);
+    if (!res.ok) throw new Error(`Token fetch failed: ${res.status}`);
+    const { token, endpoint } = await res.json();
+    return { endpoint, token };
+  }
+
+  /**
+   * Push one batch of local writes to the server.
+   *
+   * The sync engine guarantees:
+   *   - We're only called when there's work to do.
+   *   - Each `tx` is a coherent unit — if the engine called this with five
+   *     ops and we ack four, the unacked one will be retried.
+   *   - `tx.complete()` MUST be called only after the server has confirmed
+   *     durability. If we ack before the POST succeeds, a crash here loses
+   *     the user's write.
+   *
+   * If `uploadData` throws, the sync engine backs off and retries the same
+   * transaction later. That's the desired behaviour for transient errors
+   * (network blip, server restart). For permanent errors (validation
+   * failure, schema mismatch) you'd want to either tx.complete() to drop
+   * the bad write or surface it to the user — neither is implemented here
+   * because the server route accepts everything the schema allows.
+   */
+  async uploadData(database: AbstractPowerSyncDatabase) {
+    const tx = await database.getNextCrudTransaction();
+    if (!tx) return;
+
+    const ops = tx.crud.map((entry: CrudEntry) => ({
+      table: entry.table,
+      op: entry.op,
+      id: entry.id,
+      data: entry.opData,
+    }));
+
+    const res = await fetch(SYNC_UPLOAD_ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ops }),
+    });
+
+    if (!res.ok) throw new Error(`Sync upload failed: ${res.status}`);
+    await tx.complete();
+  }
+}

package/templates/realtime-app/components/ui/src/lib/schema.ts

@@ -0,0 +1,35 @@
+/**
+ * Client-side schema declaration.
+ *
+ * This is the contract between the local sync engine and the Postgres tables
+ * defined in `components/server/migrations/`. The engine uses it to:
+ *   - shape the local SQLite tables that mirror Postgres,
+ *   - decide which incoming rows to accept,
+ *   - type the results returned from `useQuery`.
+ *
+ * Rules of thumb:
+ *   - Every Postgres table the UI reads from MUST appear here.
+ *   - Column names must match the Postgres column names exactly.
+ *   - Primary keys (`id`) are implicit — don't redeclare them.
+ *   - SQLite has fewer types than Postgres. Use `column.text` for strings,
+ *     `column.integer` for numbers and booleans (0/1), `column.real` for
+ *     floats. Timestamps are stored as `integer` (epoch millis) for cheap
+ *     comparisons.
+ *
+ * To add a new table:
+ *   1. Add the migration in `components/server/migrations/`.
+ *   2. Add a `new Table({...})` for it here.
+ *   3. Add it to the `new Schema({...})` call below.
+ *   4. Restart the server — `deploy.ts` will pick it up and tell the sync
+ *      service to start replicating it.
+ */
+
+import { column, Schema, Table } from '@powersync/web';
+
+const items = new Table({
+  text: column.text,
+  done: column.integer,
+  created_at: column.integer,
+});
+
+export const appSchema = new Schema({ items });

package/templates/realtime-app/components/ui/src/lib/sync.ts

@@ -0,0 +1,24 @@
+/**
+ * Local sync database.
+ *
+ * This is the single instance every component reads from and writes to. Under
+ * the hood it's a SQLite database running in the browser (via WASM) that
+ * mirrors a subset of the server-side Postgres tables. Reads are local and
+ * synchronous-fast; writes go to the local DB first and are streamed to the
+ * server in the background by the connector.
+ *
+ * The schema here MUST match the columns declared in `schema.ts`. The local
+ * engine refuses to materialise rows whose columns it doesn't know about.
+ */
+
+import { PowerSyncDatabase } from '@powersync/web';
+import { appSchema } from './schema';
+
+export const db = new PowerSyncDatabase({
+  schema: appSchema,
+  // `database.dbFilename` is the IndexedDB key used to persist the local
+  // SQLite file across reloads. Each app gets its own — namespaced by app
+  // name to avoid collisions when multiple apps run on the same origin
+  // during development.
+  database: { dbFilename: '{{APP_NAME}}.db' },
+});

package/templates/realtime-app/components/ui/src/main.tsx

@@ -0,0 +1,49 @@
+/**
+ * UI entry point.
+ *
+ * Boot order:
+ *   1. Mount React with the local sync database as context. The DB instance
+ *      is already constructed (see `lib/sync.ts`) but its WASM SQLite engine
+ *      hasn't been initialised yet — that happens asynchronously.
+ *   2. Kick off `db.init()` (open the local SQLite file) and `db.connect()`
+ *      (open the WebSocket to the sync service). Both are fire-and-forget;
+ *      the React tree renders immediately and `useQuery` calls return empty
+ *      arrays until the local store is ready, then update reactively.
+ *
+ * Why we don't `await` these calls:
+ *   - The local SQLite engine is loaded from a WASM module. On a cold cache
+ *     it can take a second or two. Awaiting it here blocks the browser's
+ *     first paint and the user sees a blank page for that whole window.
+ *   - Connecting to the sync service requires a network round-trip to fetch
+ *     a JWT and open a WebSocket. The UI should be visible and interactive
+ *     long before that resolves.
+ *
+ * The PowerSync React adapter handles the "not yet ready" state correctly —
+ * components reading from the DB just see an empty result until it isn't.
+ */
+
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { PowerSyncContext } from '@powersync/react';
+import { registerSW } from 'virtual:pwa-register';
+import { db } from './lib/sync';
+import { AppConnector } from './lib/connector';
+import App from './App';
+import './styles/theme.css';
+
+db.init();
+db.connect(new AppConnector());
+
+// Register the service worker in production builds only. The plugin's
+// `virtual:pwa-register` is a no-op in dev (devOptions.enabled: false).
+// `autoUpdate` swaps to a new SW as soon as one is available; subsequent
+// reloads serve from the new cache.
+registerSW({ immediate: true });
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <PowerSyncContext.Provider value={db}>
+      <App />
+    </PowerSyncContext.Provider>
+  </StrictMode>
+);