tilt/DEPLOY.md

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:

npx wrangler login
# or: npm run cf:whoami

Preferred: Workers (static assets)

Config lives in wrangler.jsonc. Assets come from dist/ after a Vite production build.

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:

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:

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

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

# 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