Prepare Cloudflare Workers/Pages deploy for the static front-end.

Add wrangler assets config, multi-page Vite build (game + studio), cache/WASM headers, and deploy scripts so `npm run deploy` publishes dist.
2026-08-03 10:33:24 -05:00
parent dd819e991d
commit 7a196b6571
8 changed files with 1724 additions and 3 deletions
@@ -0,0 +1,119 @@
+# Deploying tilt
+
+tilt is a **static Vite front-end** (Three.js + Box3D WASM). There is no API
+server yet. Cloudflare **Workers Static Assets** is the primary target;
+**Pages** is a one-liner alternative if you prefer Git/dashboard deploys.
+
+## Prerequisites
+
+1. Cloudflare account  
+2. Auth once on this machine:
+
+```bash
+npx wrangler login
+# or: npm run cf:whoami
+```
+
+## Preferred: Workers (static assets)
+
+Config lives in [`wrangler.jsonc`](wrangler.jsonc). Assets come from `dist/`
+after a Vite production build.
+
+```bash
+npm install
+npm run deploy:dry   # validate upload without publishing
+npm run deploy       # build + wrangler deploy
+```
+
+That publishes a Worker named **`tilt`** serving:
+
+| Path | App |
+|------|-----|
+| `/` | Game (menu → 1v1 / 3v3) |
+| `/character.html` | Gear / animation studio |
+
+URL shape after first deploy: `https://tilt.<your-subdomain>.workers.dev`
+
+### Custom domain
+
+Dashboard → Workers & Pages → **tilt** → Settings → Domains, or:
+
+```bash
+npx wrangler domains add tilt.example.com
+```
+
+(Exact CLI may vary by Wrangler version; dashboard is fine.)
+
+## Alternative: Cloudflare Pages
+
+Same build output, Pages project instead of a Worker:
+
+```bash
+npm run pages:deploy
+# → wrangler pages deploy dist --project-name=tilt
+```
+
+Or connect the Git remote in the dashboard:
+
+| Setting | Value |
+|---------|--------|
+| Production branch | `main` |
+| Build command | `npm run build` |
+| Build output directory | `dist` |
+| Root directory | `/` (repo root) |
+| Node version | 20+ |
+
+`public/_headers` is copied into `dist/` by Vite and applies on both Workers
+assets and Pages.
+
+## Local production check
+
+```bash
+npm run build
+npm run preview      # Vite static server on dist/
+# or, after wrangler is installed:
+npx wrangler dev     # serves assets via Workers runtime locally
+```
+
+## What is *not* deployed
+
+- `test/`, `tools/` (Node harnesses, Puppeteer captures)
+- `shots/`, `node_modules/`, source maps (unless you opt in)
+- Server/netcode — still pure client sim
+
+When you add an API later, keep this assets config and introduce a Worker
+`main` (or Pages Functions) beside it; SPA/static hosting stays the same.
+
+## CI sketch
+
+```yaml
+# e.g. Gitea Actions / GitHub Actions
+- run: npm ci
+- run: npm test
+- run: npm run build
+- run: npx wrangler deploy
+  env:
+    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+Create an API token with **Workers Scripts:Edit** (and **Account:Read**).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `wrangler login` / auth errors | `npx wrangler login` or set `CLOUDFLARE_API_TOKEN` |
+| Blank page, missing WASM | Confirm `dist/assets/*.wasm` exists after build; hard-refresh |
+| 404 on `/character` | Use `/character.html` (multi-page, not SPA rewrite) |
+| Huge first load | Expected (~0.7 MB JS + ~0.8 MB WASM); cached after first visit |
+| `node:module` warning in build | Harmless browser stub for box3d’s Node path; WASM path is used |
+
+## Files
+
+| File | Role |
+|------|------|
+| `wrangler.jsonc` | Workers name, assets directory, observability |
+| `public/_headers` | Cache + WASM content-type hints |
+| `vite.config.js` | Multi-page entries (`index` + `character`) |
+| `package.json` | `deploy`, `deploy:dry`, `pages:deploy` scripts |