User GuideDeployment
Cloudflare Workers Deployment
Deploy TanStack Start to Cloudflare Workers (Hyperdrive and D1 supported)
This guide explains how to deploy TinyShip's TanStack Start app to Cloudflare Workers.
Scope: apps/tanstack-app only.
AI One-Click Setup: Users with Agent Skills installed can tell their AI "all-in Cloudflare" to use the tinyship-cloudflare skill for one-stop Workers + D1/Hyperdrive + R2 + Email + Turnstile setup.
Database Options
| Option | Database | DB_DIALECT | Best for |
|---|---|---|---|
| Hyperdrive (recommended) | PostgreSQL | pg | Reuse existing PG and keep all frameworks aligned |
| Cloudflare D1 | SQLite (D1) | d1 | All-in Cloudflare and lower ops overhead |
| Neon Serverless | PostgreSQL (HTTP) | pg | Alternative path for Neon users |
Deployment Steps
1) Log in
cd apps/tanstack-app
npx wrangler login2) Configure database
Option A: Hyperdrive + PostgreSQL
npx wrangler hyperdrive create tinyship-db \
--connection-string="postgresql://user:password@host:5432/dbname"wrangler.jsonc:
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "<your-hyperdrive-id>",
"localConnectionString": "postgresql://user:pwd@localhost:5432/tinyship"
}
]Option B: D1 (SQLite)
cd apps/tanstack-app
npx wrangler d1 create tinyship-dbwrangler.jsonc:
"vars": {
"DB_DIALECT": "d1",
"APP_BASE_URL": "https://your-domain.com",
"BETTER_AUTH_URL": "https://your-domain.com"
},
"d1_databases": [
{
"binding": "DB",
"database_name": "tinyship-db",
"database_id": "<your-d1-database-id>"
}
]When using D1, remove or comment out hyperdrive config.
D1 Migrations and Initialization
pnpm db:generate:sqlite
npx wrangler d1 migrations apply tinyship-db
npx wrangler d1 migrations apply tinyship-db --local3) Configure secrets
npx wrangler secret put BETTER_AUTH_SECRET
npx wrangler secret put DATABASE_URL4) Local preview
cd apps/tanstack-app
pnpm dev:cf5) Deploy
cd apps/tanstack-app
pnpm run deploy:cfNotes
- This path is TanStack Start only (
apps/tanstack-app). Next.js and Nuxt stay on Node. - Workers supports both
pg(Hyperdrive) andd1. - SQLite and D1 share the same schema set.
- If you deploy Next, Nuxt, and TanStack together, Hyperdrive plus PostgreSQL is the shared database.
Troubleshooting
| Symptom | What to check |
|---|---|
| D1 queries fail while Hyperdrive is set | Remove or comment out the hyperdrive block when DB_DIALECT is d1 |
BETTER_AUTH_SECRET missing at runtime | npx wrangler secret put, not only vars in wrangler.jsonc |
| Local preview differs from deploy | pnpm dev:cf uses localConnectionString or --local D1 migrations |
| Migrations not applied | pnpm db:generate:sqlite, then npx wrangler d1 migrations apply tinyship-db |