`, favicon, and body of `Root()` to\nmatch your app's existing `index.html`, and stamp anything else your shell\nreferences directly (images, css) with `immutableFileUrl()`.\n\n1. Create `frontend/root.tsx`:\n\n```tsx\n/** @jsxImportSource npm:hono@4/jsx */\nimport { raw } from \"npm:hono@4/html\";\nimport { immutableFileUrl } from \"https://esm.town/v/std/utils/index.ts\";\n\n// The HTML shell for the app. It is never cached, so immutableFileUrl can stamp\n// the current val version into each asset URL — the browser caches those\n// immutably, and publishing the val changes the URLs, refetching exactly once.\nexport function Root() {\n return (\n <>\n {raw(\"<!DOCTYPE html>\")}\n <html lang=\"en\">\n <head>\n <meta charSet=\"UTF-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n <title>React Hono Val Town Starter

[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_254":255,"_256":257},"routes/_app.x.$handle.$name",{"_104":103,"_37":49,"_113":94,"_32":114,"_13":14,"_115":-5,"_11":116,"_117":118,"_119":120,"_121":122,"_123":124,"_26":-5,"_125":-5,"_126":-5,"_127":30,"_128":129,"_130":63,"_131":-5,"_132":-5,"_133":134},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":18,"_19":-5},"project",{"_47":48,"_37":49,"_42":50,"_51":-5,"_52":30,"_53":54,"_55":54,"_56":57,"_58":-5,"_19":59,"_60":61,"_62":63,"_64":-5,"_65":-5,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":-5,"_77":78,"_79":78,"_80":81,"_82":81,"_83":81,"_84":78,"_85":78,"_86":87,"_88":89,"_90":91,"_92":30},"version",2,"changes",[25],"aiChatInfo",{"_20":21,"_22":-5,"_23":-5,"_24":-5},"userId","aiChatMessageId","4de896d6-46d8-4d60-9727-8806407e93cf","aiChatThreadId","aiChatThreadUserId","aiChatThreadTitle",{"_26":27,"_28":-7,"_29":30,"_31":30,"_32":33,"_34":33},"file",{"_35":36,"_37":33,"_38":39,"_40":41,"_42":43,"_44":14,"_45":46,"_29":30},"previous","deleted",false,"deletedHere","path","cards.ts","latestPath","fileId","04e5b21e-b290-11f1-b02b-1607ee4eb77e","name","fileType","script","content","// ---------------------------------------------------------------------------\n// Card engine — the \"card is a key, not a wallet\" model.\n//\n// The QR code only ever contains a random CODE. All balances live here, in the\n// database, behind the server. Nothing the card says is trusted.\n// ---------------------------------------------------------------------------\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\n\n// Money is stored in CENTS as integers — never floats (no 0.1 + 0.2 problems).\nexport type Card = {\n code: string;\n balance: number; // cents, current\n initial: number; // cents, face value when activated\n status: \"inactive\" | \"active\" | \"void\";\n batch: string | null;\n note: string | null;\n created_at: string;\n activated_at: string | null;\n};\n\nexport type Txn = {\n id: number;\n code: string;\n kind: \"generate\" | \"activate\" | \"redeem\" | \"refund\" | \"topup\" | \"void\";\n amount: number; // cents, signed (negative = spent)\n balance_after: number;\n store: string | null;\n created_at: string;\n};\n\n// ----------------------------- Schema -----------------------------\nlet schemaReady: Promise | null = null;\n\nexport function ensureSchema(): Promise {\n // Idempotent + cached so we don't re-run DDL on every request.\n if (!schemaReady) {\n schemaReady = (async () => {\n await sqlite.batch([\n {\n sql: `CREATE TABLE IF NOT EXISTS cards (\n code TEXT PRIMARY KEY,\n balance INTEGER NOT NULL DEFAULT 0,\n initial INTEGER NOT NULL DEFAULT 0,\n status TEXT NOT NULL DEFAULT 'inactive',\n batch TEXT,\n note TEXT,\n created_at TEXT NOT NULL,\n activated_at TEXT\n )`,\n },\n {\n sql: `CREATE TABLE IF NOT EXISTS card_txns (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n code TEXT NOT NULL,\n kind TEXT NOT NULL,\n amount INTEGER NOT NULL,\n balance_after INTEGER NOT NULL,\n store TEXT,\n created_at TEXT NOT NULL\n )`,\n },\n { sql: `CREATE INDEX IF NOT EXISTS idx_txn_code ON card_txns (code)` },\n { sql: `CREATE INDEX IF NOT EXISTS idx_cards_batch ON cards (batch)` },\n ]);\n })();\n }\n return schemaReady;\n}\n\n// --------------------------- Code generation ---------------------------\n// Unambiguous alphabet: no I, O, 0, 1 — so humans can read a card aloud.\nconst ALPHABET = \"ABCDEFGHJKLMNPQRSTUVWXYZ23456789\";\n\nfunction randomCode(prefix: string, groups = 3, size = 4): string {\n const bytes = new Uint8Array(groups * size);\n crypto.getRandomValues(bytes);\n const chars = Array.from(bytes, (b) => ALPHABET[b % ALPHABET.length]);\n const parts: string[] = [];\n for (let i = 0; i < groups; i++) {\n parts.push(chars.slice(i * size, (i + 1) * size).join(\"\"));\n }\n return `${prefix}-${parts.join(\"-\")}`;\n}\n\nfunction now(): string {\n return new Date().toISOString();\n}\n\n// --------------------------- Lifecycle ---------------------------\n\n/**\n * Create a batch of cards. They start INACTIVE and worth nothing — a box of\n * stolen, unprinted-in-store cards is worthless until activated at the till.\n */\nexport async function generateCards(opts: {\n count: number;\n amountCents: number;\n batch?: string;\n prefix?: string;\n note?: string;\n}): Promise {\n await ensureSchema();\n const count = Math.min(Math.max(1, Math.floor(opts.count)), 500);\n const prefix = (opts.prefix || \"NBL\").toUpperCase().slice(0, 8);\n const batch = opts.batch || `B${Date.now().toString(36).toUpperCase()}`;\n const created: Card[] = [];\n\n // Retry on the astronomically unlikely code collision.\n for (let i = 0; i < count; i++) {\n let inserted = false;\n for (let attempt = 0; attempt < 5 && !inserted; attempt++) {\n const code = randomCode(prefix);\n const res = await sqlite.execute({\n sql: `INSERT OR IGNORE INTO cards\n (code, balance, initial, status, batch, note, created_at)\n VALUES (?, 0, ?, 'inactive', ?, ?, ?)`,\n args: [code, opts.amountCents, batch, opts.note ?? null, now()],\n });\n if (res.rowsAffected > 0) {\n inserted = true;\n created.push({\n code,\n balance: 0,\n initial: opts.amountCents,\n status: \"inactive\",\n batch,\n note: opts.note ?? null,\n created_at: now(),\n activated_at: null,\n });\n }\n }\n }\n return created;\n}\n\nexport async function getCard(code: string): Promise {\n await ensureSchema();\n const res = await sqlite.execute({\n sql: \"SELECT * FROM cards WHERE code = ?\",\n args: [normalize(code)],\n });\n return (res.rows[0] as Card | undefined) ?? null;\n}\n\nexport async function listCards(limit = 50, batch?: string): Promise {\n await ensureSchema();\n const res = batch\n ? await sqlite.execute({\n sql: \"SELECT * FROM cards WHERE batch = ? ORDER BY created_at DESC LIMIT ?\",\n args: [batch, limit],\n })\n : await sqlite.execute({\n sql: \"SELECT * FROM cards ORDER BY created_at DESC LIMIT ?\",\n args: [limit],\n });\n return res.rows as unknown as Card[];\n}\n\n/** Sell a card: give it its face value and make it spendable. */\nexport async function activateCard(\n code: string,\n amountCents?: number,\n): Promise {\n await ensureSchema();\n const c = normalize(code);\n const card = await getCard(c);\n if (!card) throw new Error(\"Card not found\");\n if (card.status === \"void\") throw new Error(\"Card is void\");\n if (card.status === \"active\") throw new Error(\"Card is already active\");\n\n const value = amountCents ?? card.initial;\n const ts = now();\n await sqlite.batch([\n {\n sql: `UPDATE cards SET status = 'active', balance = ?, initial = ?, activated_at = ?\n WHERE code = ? AND status = 'inactive'`,\n args: [value, value, ts, c],\n },\n {\n sql: `INSERT INTO card_txns (code, kind, amount, balance_after, store, created_at)\n VALUES (?, 'activate', ?, ?, NULL, ?)`,\n args: [c, value, value, ts],\n },\n ]);\n return (await getCard(c))!;\n}\n\n/**\n * Spend. The single conditional UPDATE is what prevents double-spend: if two\n * registers scan the same card at once, only one update can match the row.\n */\nexport async function redeemCard(\n code: string,\n amountCents: number,\n store?: string,\n): Promise {\n await ensureSchema();\n const c = normalize(code);\n if (!Number.isInteger(amountCents) || amountCents <= 0) {\n throw new Error(\"Amount must be a positive number of cents\");\n }\n\n const card = await getCard(c);\n if (!card) throw new Error(\"Card not found\");\n if (card.status === \"void\") throw new Error(\"Card is void\");\n if (card.status === \"inactive\") throw new Error(\"Card is not active — activate it first\");\n if (card.balance < amountCents) throw new Error(\"Insufficient balance\");\n\n const res = await sqlite.execute({\n sql: `UPDATE cards SET balance = balance - ?\n WHERE code = ? AND status = 'active' AND balance >= ?`,\n args: [amountCents, c, amountCents],\n });\n if (res.rowsAffected === 0) {\n throw new Error(\"Redeem failed — card changed state. Try again.\");\n }\n\n const after = (await getCard(c))!;\n await sqlite.execute({\n sql: `INSERT INTO card_txns (code, kind, amount, balance_after, store, created_at)\n VALUES (?, 'redeem', ?, ?, ?, ?)`,\n args: [c, -amountCents, after.balance, store ?? null, now()],\n });\n return after;\n}\n\nexport async function topUp(code: string, amountCents: number): Promise {\n return adjust(code, amountCents, \"topup\");\n}\n\nexport async function refund(code: string, amountCents: number): Promise {\n return adjust(code, amountCents, \"refund\");\n}\n\nasync function adjust(\n code: string,\n amountCents: number,\n kind: \"topup\" | \"refund\",\n): Promise {\n await ensureSchema();\n const c = normalize(code);\n if (!Number.isInteger(amountCents) || amountCents <= 0) {\n throw new Error(\"Amount must be a positive number of cents\");\n }\n const card = await getCard(c);\n if (!card) throw new Error(\"Card not found\");\n if (card.status === \"void\") throw new Error(\"Card is void\");\n\n await sqlite.execute({\n sql: \"UPDATE cards SET balance = balance + ? WHERE code = ?\",\n args: [amountCents, c],\n });\n const after = (await getCard(c))!;\n await sqlite.execute({\n sql: `INSERT INTO card_txns (code, kind, amount, balance_after, store, created_at)\n VALUES (?, ?, ?, ?, NULL, ?)`,\n args: [c, kind, amountCents, after.balance, now()],\n });\n return after;\n}\n\nexport async function voidCard(code: string): Promise {\n await ensureSchema();\n const c = normalize(code);\n const card = await getCard(c);\n if (!card) throw new Error(\"Card not found\");\n\n await sqlite.batch([\n { sql: \"UPDATE cards SET status = 'void', balance = 0 WHERE code = ?\", args: [c] },\n {\n sql: `INSERT INTO card_txns (code, kind, amount, balance_after, store, created_at)\n VALUES (?, 'void', ?, 0, NULL, ?)`,\n args: [c, -card.balance, now()],\n },\n ]);\n return (await getCard(c))!;\n}\n\nexport async function listTxns(code?: string, limit = 100): Promise {\n await ensureSchema();\n const res = code\n ? await sqlite.execute({\n sql: \"SELECT * FROM card_txns WHERE code = ? ORDER BY id DESC LIMIT ?\",\n args: [normalize(code), limit],\n })\n : await sqlite.execute({\n sql: \"SELECT * FROM card_txns ORDER BY id DESC LIMIT ?\",\n args: [limit],\n });\n return res.rows as unknown as Txn[];\n}\n\nexport async function stats(): Promise<{\n total: number;\n active: number;\n inactive: number;\n outstandingCents: number;\n}> {\n await ensureSchema();\n const res = await sqlite.execute({\n sql: `SELECT\n COUNT(*) AS total,\n SUM(CASE WHEN status = 'active' THEN 1 ELSE 0 END) AS active,\n SUM(CASE WHEN status = 'inactive' THEN 1 ELSE 0 END) AS inactive,\n SUM(CASE WHEN status = 'active' THEN balance ELSE 0 END) AS outstanding\n FROM cards`,\n });\n const r = res.rows[0] as Record;\n return {\n total: Number(r.total ?? 0),\n active: Number(r.active ?? 0),\n inactive: Number(r.inactive ?? 0),\n outstandingCents: Number(r.outstanding ?? 0),\n };\n}\n\n/** Accept codes with spaces, lowercase, or missing dashes. */\nexport function normalize(code: string): string {\n return code.trim().toUpperCase().replace(/\\s+/g, \"\");\n}\n\n// --------------------------- Money helpers ---------------------------\nexport function toCents(dollars: number | string): number {\n const n = typeof dollars === \"string\" ? Number(dollars) : dollars;\n if (!Number.isFinite(n) || n < 0) throw new Error(\"Invalid amount\");\n return Math.round(n * 100);\n}\n\nexport function fmtCents(cents: number): string {\n return `$${(cents / 100).toFixed(2)}`;\n}","createdAt",["D",1789646705223],"branchVersion","branchId","57a6487e-c99e-4332-92e2-6d15ca868b6a","id","dc85dda4-95e6-4479-97de-662e1fc771d9","card-redeem",["D",1789646679801],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Gift-card API with QR redeem scanner UI","imageUrl","d6d32317-8e12-4003-b452-8bd4229aeca3","pinnedFileId","01a0af41-2f44-7689-90a1-221a99b90e3a","pinPreview",true,"pinMigrated","screenshotVersion","likeCount",0,"orgId","01a0a0c6-84d9-72a5-9904-46bf8e8a5e5f","tursoName","dc85dda495e6447997de662e1fc771d9","tursoHostname","dc85dda495e6447997de662e1fc771d9-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789650647385],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_104":103,"_112":108},"org",{"_104":103,"_105":106,"_107":108,"_19":59,"_109":110,"_111":30},"branch",{"_13":93,"_37":94,"_47":46,"_95":48,"_96":-5,"_97":-5,"_98":-5,"_99":-5,"_100":-5,"_101":49,"_102":103},"isOwned",17,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","IceyDomain","handle","displayName","Nathaniel Barrett","avatar","https://avatars.githubusercontent.com/u/174974902?v=4","tier","free","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_47":48,"_37":49,"_42":249,"_51":-5,"_52":30,"_53":54,"_55":54,"_56":57,"_58":-5,"_19":59,"_60":61,"_62":63,"_64":-5,"_65":-5,"_66":67,"_68":69,"_70":71,"_72":73,"_74":250,"_76":-5,"_77":78,"_79":78,"_80":81,"_82":81,"_83":81,"_84":78,"_85":78,"_86":251,"_88":252,"_90":253,"_92":30},"tree",[181,188,189,190,191],"files",[181,182,183,184,185,186,187,188,189,190,191],"counts",{"_171":67,"_172":143,"_173":67,"_174":175,"_176":177},"contents",[135,136,137,138,139],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_47":165,"_37":166,"_35":167,"_142":-5,"_45":46,"_44":143,"_144":63,"_42":168,"_13":67,"_38":169,"_40":-5,"_29":30,"_148":-5,"_32":170},{"_47":159,"_37":160,"_35":161,"_142":-5,"_45":46,"_44":143,"_144":63,"_42":162,"_13":67,"_38":26,"_40":163,"_29":30,"_148":-5,"_32":164},{"_47":153,"_37":154,"_35":155,"_142":-5,"_45":46,"_44":143,"_144":30,"_42":156,"_13":67,"_38":26,"_40":157,"_29":30,"_148":-5,"_32":158},{"_47":150,"_37":33,"_35":36,"_142":-5,"_45":46,"_44":14,"_144":30,"_42":151,"_13":67,"_38":39,"_40":41,"_29":30,"_148":-5,"_32":152},{"_47":140,"_37":141,"_35":61,"_142":-5,"_45":46,"_44":143,"_144":30,"_42":145,"_13":67,"_38":146,"_40":147,"_29":30,"_148":49,"_32":149},"c6bfe94a-1e06-4e85-9d4f-97fe975568bf","index.ts","parentId",1,"latest",["D",1789646679801],"http","import { parseVal, serveImmutableFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport { Hono } from \"npm:hono\";\nimport { Root } from \"./frontend/root.tsx\";\n\nconst app = new Hono();\n\n// Serve the (never-cached) HTML shell at the root /\napp.get(\"/\", (c) => c.html(Root()));\n\n// Serve frontend files at the version-addressed URLs Root() stamps, cached immutably\napp.get(\"/__immutable/*\", (c) => serveImmutableFile(c.req.path));\n\n// View source redirect\napp.get(\"/source\", (c) => c.redirect(parseVal().links.self.val));\n\n// Add your API routes here\n// app.get(\"/api/data\", c => c.json({ hello: \"world\" }));\n\n// Unwrap and rethrow Hono errors as the original error\n// If you delete this, all errors will be \"Internal Server Error\"\napp.onError((err) => Promise.reject(err));\n\n// HTTP vals expect an exported \"fetch handler\"\n// This is how you \"run the server\" in Val Town with Hono\nexport default app.fetch;\n","label",[141],"e1b1a67c-fb9b-436a-aca5-60b0f32f93f5",["D",1789646705223],[33],"1fe5fc1a-d1ff-4ef6-95d7-e16ed699a102","README.md","01a0af41-2f44-7689-90a1-1c808e231f8d",["D",1789646679801],"# React + Hono Starter\n\nA minimal starter template for building client-side React apps with a Hono\nbackend on Val Town. Click **Remix** to get your own copy.\n\n## Picking a starter\n\n| Starter | When to pick it |\n| --- | --- |\n| [`basic-html-starter`](https://www.val.town/x/templates/basic-html-starter) | Static HTML pages. Sprinkle of vanilla JS. No server-side rendering. |\n| [`hono-jsx-starter`](https://www.val.town/x/templates/hono-jsx-starter) | Dynamic server-rendered HTML with JSX. API routes. No React, no SPA. |\n| **[`react-hono-starter`](https://www.val.town/x/templates/react-hono-starter)** *(you're here)* | Client-side React SPA with a Hono API backend. |\n\n**Want to build UI?** Start writing React components in\n[`frontend/components/`](/frontend/components/). Import them into `App.tsx` and\nyou're good to go. Styling is [Twind](https://twind.style/) — just use Tailwind\nutility classes, zero config.\n\n**Want to add an API?** Add routes in [`index.ts`](/index.ts) (there's a\ncommented-out example). Fetch them from your React components.\n\n## Architecture\n\n```mermaid\ngraph LR\n Browser -->|\"GET /\"| Hono[\"index.ts
(Hono server)\"]\n Hono -->|serves| HTML[\"root.tsx\"]\n HTML -->|loads| Entry[\"index.tsx\"]\n Entry -->|renders| App[\"App.tsx\"]\n App -->|renders| Counter[\"Counter.tsx\"]\n```\n\n## File structure\n\n```\nindex.ts ← Hono backend (serves frontend + API routes)\nfrontend/\n root.tsx ← HTML shell (stamps immutable asset URLs)\n index.tsx ← React entrypoint (mounts )\n favicon.svg ← App icon\n components/\n App.tsx ← Root component (layout + view source link)\n Counter.tsx ← Example component with state\n```\n\n## How it works\n\n1. **`index.ts`** is the HTTP entrypoint — a Hono server that serves the\n frontend and any API routes you add.\n2. **`frontend/root.tsx`** is the HTML shell — it loads Twind and stamps\n immutable asset URLs for the favicon and React entrypoint.\n3. **`frontend/index.tsx`** mounts the React app.\n4. **`frontend/components/App.tsx`** is the root layout — add new components\n alongside it.\n5. **`frontend/components/Counter.tsx`** is an example stateful component —\n replace it with your own!\n\n## Next steps\n\n- Add API routes in `index.ts`\n- Add new components in `frontend/components/`\n- Add a SQLite database — see the\n [React Hono Example](https://www.val.town/x/stevekrouse/reactHonoExample) for\n a full-stack example with database, queries, and shared types\n\nTemplate updates and upgrade paths for existing remixes: [CHANGELOG.md](/CHANGELOG.md)\n",[154],"c9a644e8-51ac-452f-a73c-57220fd87ef2","CHANGELOG.md","01a0af41-2f44-7689-90a1-1b65a816daa2",["D",1789646679801],"# Changelog\n\n## 2026-07-30 — Immutable asset caching\n\nFrontend files are now served at version-addressed URLs\n(`/__immutable/45/frontend/index.tsx`) with\n`Cache-Control: public, max-age=31536000, immutable`, so repeat visits load the\nwhole client graph from the browser cache — roughly 3× faster (~665ms → ~157ms\nmeasured). Publishing your val bumps its version, which changes every URL, so\ncaches invalidate automatically. Old-version URLs return 404 after a publish\n(like Next.js build assets); a reload picks up the new version.\n\nWhat changed in the template:\n\n- `frontend/index.html` → [`frontend/root.tsx`](/frontend/root.tsx): the HTML\n shell is now JSX and stamps asset URLs with `immutableFileUrl()`\n- [`index.ts`](/index.ts): serves `Root()` at `/`, and one\n `app.get(\"/__immutable/*\", (c) => serveImmutableFile(c.req.path))` route\n serves all frontend files\n\n### Upgrading an existing remix\n\nYour copy of this template doesn't update automatically. Two options:\n\n**Minimal (most of the benefit):** point both routes at `serveImmutableFile` —\nyour existing bare URLs redirect into versioned space, the new route serves\nthem, and the whole module graph gets cached (costs one redirect per page view):\n\n```ts\nimport { serveImmutableFile } from \"https://esm.town/v/std/utils/index.ts\";\n\napp.get(\"/__immutable/*\", (c) => serveImmutableFile(c.req.path));\napp.get(\"/frontend/**/*\", (c) => serveImmutableFile(c.req.path)); // was serveFile\n```\n\n**Full upgrade (also removes the redirect):** three self-contained steps —\nno other files needed. Adjust the ``, favicon, and body of `Root()` to\nmatch your app's existing `index.html`, and stamp anything else your shell\nreferences directly (images, css) with `immutableFileUrl()`.\n\n1. Create `frontend/root.tsx`:\n\n```tsx\n/** @jsxImportSource npm:hono@4/jsx */\nimport { raw } from \"npm:hono@4/html\";\nimport { immutableFileUrl } from \"https://esm.town/v/std/utils/index.ts\";\n\n// The HTML shell for the app. It is never cached, so immutableFileUrl can stamp\n// the current val version into each asset URL — the browser caches those\n// immutably, and publishing the val changes the URLs, refetching exactly once.\nexport function Root() {\n return (\n <>\n {raw(\"<!DOCTYPE html>\")}\n <html lang=\"en\">\n <head>\n <meta charSet=\"UTF-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n <title>React Hono Val Town Starter\n

Diff · v2