ryanfitzpatrickio
7a196b6571
Add wrangler assets config, multi-page Vite build (game + studio), cache/WASM headers, and deploy scripts so `npm run deploy` publishes dist.
120 lines
3.2 KiB
Markdown
120 lines
3.2 KiB
Markdown
# 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 |
|