One-stop wizard to configure the full Cloudflare stack for TinyShip (TanStack Start).
This is a conversational, step-by-step wizard. You MUST ask the user at each decision point and wait for their answer before proceeding. NEVER make choices on the user's behalf.
Step 0: Detect Template & Route
First, read ../../references/template-detection.md and detect which template the current project is.
If the project is tinyship-cf (Cloudflare-only template)
The project is already Cloudflare-native — bindings, D1, and the Workers setup are preconfigured. Do NOT run framework cleanup or wrangler scaffolding. Go directly to the Fast Path below.
If the project is shipeasy (multi-framework)
⛔ STOP — You MUST tell the user and ask before proceeding.
TinyShip now has a dedicated Cloudflare template (tinyship-cf) that ships preconfigured for Workers (no hacks, no framework cleanup needed). For NEW Cloudflare projects, starting from tinyship-cf is recommended.
- Continue here — configure Cloudflare in this shipeasy project (makes sense if you already built features on it)
- Switch to tinyship-cf — start fresh from the dedicated template and migrate your changes manually
If the user chooses to continue, follow the Full Wizard below.
Fast Path (tinyship-cf projects)
1. Wrangler Login
cd apps/tanstack-app
npx wrangler login
npx wrangler whoami # capture the Account ID
If already logged in, skip and tell the user.
2. Local env
cp apps/tanstack-app/.dev.vars.example apps/tanstack-app/.dev.vars
Set BETTER_AUTH_SECRET (openssl rand -hex 32). Verify local dev:
pnpm dev # http://localhost:7001
3. Remote database
The D1 database is already bound in wrangler.jsonc. Apply migrations and verify:
npx wrangler d1 migrations apply tinyship-db --remote
For Hyperdrive + PostgreSQL instead of D1, read and follow references/hyperdrive-setup.md.
4. Secrets
⛔ STOP — ask the user which features they use, then set only those secrets.
npx wrangler secret put BETTER_AUTH_SECRET # required
# Payments (as needed): STRIPE_SECRET_KEY, PAYPAL_CLIENT_ID/SECRET,
# DODO_PAYMENTS_API_KEY/WEBHOOK_KEY, CREEM_API_KEY/WEBHOOK_SECRET
# AI image/video (as needed): QWEN_API_KEY, FAL_API_KEY,
# GOOGLE_GENERATIVE_AI_API_KEY, VOLCENGINE_ACCESS_KEY_ID
# Email: RESEND_API_KEY
Notes:
- Chat AI needs no secret — it runs on Workers AI + AI Gateway. Third-party chat keys (OpenAI/DeepSeek) are managed in the AI Gateway dashboard (BYOK).
AI_GATEWAY_IDdefaults todefault; if the user's gateway has a different name, set it inwrangler.jsoncvars.- Payment webhook URLs in each provider dashboard must point to the production domain.
5. Optional extras
Ask about each, then read and follow the matching reference:
- R2 storage — references/r2-setup.md (bucket already bound)
- Email Sending — references/email-setup.md
- Turnstile — references/turnstile-setup.md
6. Deploy
pnpm deploy:cf
Verify: home page 200, /en/pricing 200, login works. If pricing_plan table is
empty and PRICING_MODE=dynamic, log in as admin → Admin → Pricing Plans →
Import Static to populate plans.
Go to Step 8: Summary.
Full Wizard (shipeasy projects)
Scope: This wizard configures TanStack Start (
apps/tanstack-app) for Cloudflare Workers deployment. Next.js and Nuxt.js are designed for Node.js environments and do not deploy to Workers.
Prerequisites
- Node.js >= 22.20.0 — run
node -v - pnpm >= 9.0.0 — run
pnpm -v - Dependencies installed — if
node_modules/is missing, runpnpm install - A Cloudflare account — https://dash.cloudflare.com/sign-up
Step 1: Wrangler Login
Run the following to authenticate with Cloudflare:
cd apps/tanstack-app
npx wrangler login
This opens a browser for authorization. After success, verify:
npx wrangler whoami
Capture the Account ID from the output — it will be reused for R2 and Email.
If the user is already logged in (wrangler whoami shows account info), skip this step
and tell the user.
Step 2: Framework Cleanup
⛔ STOP — You MUST ask the user before proceeding.
Since Cloudflare Workers only supports TanStack Start, the Next.js and Nuxt.js apps are not needed for a Cloudflare-only deployment. Ask the user:
You've chosen the all-in Cloudflare path, which uses TanStack Start exclusively. Do you want to remove the Next.js and Nuxt.js apps from the project?
| Option | Action |
|---|---|
| Yes — clean up | Remove apps/next-app and apps/nuxt-app, update workspace config |
| No — keep them | Leave them in place (useful if you also plan Node.js deployments) |
If the user chooses Yes:
Follow the cleanup procedure from the tinyship-setup skill:
read and follow ../tinyship-setup/references/framework-cleanup.md
using TanStack Start as the kept framework.
Summary of what to do:
rm -rf apps/next-app apps/nuxt-app- Update
turbo.json— remove.nuxt/**,.output/**,.next/**from build outputs - Update root
package.json— removedev:next,build:next,dev:nuxt,build:nuxtetc., renamedev:tanstack→dev,build:tanstack→build, etc. - Update
docker-compose.yml— removenext-appandnuxt-appservices - Update
.github/workflows/ci.yml— remove build steps for deleted apps - Run
pnpm installto clean up the lockfile
After cleanup, run pnpm typecheck and pnpm build (which now point to TanStack) to verify.
If the user chooses No:
Skip this step. The other apps remain in the project but won't be deployed to Workers.
Step 3: Database — D1 or Hyperdrive
⛔ STOP — You MUST ask the user before proceeding.
Present these options and wait for the user's response:
| Option | Database | Best For |
|---|---|---|
| A | Cloudflare D1 (SQLite) | All-in Cloudflare, zero external deps, low cost |
| B | Hyperdrive + PostgreSQL | Reuse existing PG, high write concurrency, data parity with Next/Nuxt |
Explain the trade-offs:
- D1: Fully managed, included in Workers billing, 5-10 GB limit, single-writer constraint
- Hyperdrive: Needs an external PostgreSQL, but no storage limits, same DB across all 3 apps
If the user chooses D1:
Read and follow references/d1-setup.md.
If the user chooses Hyperdrive:
Read and follow references/hyperdrive-setup.md.
After database is configured, verify locally:
cd apps/tanstack-app
pnpm dev:cf
Check that the app loads and database-dependent pages work. Tell the user the results.
Step 4: R2 Storage (Optional)
⛔ STOP — You MUST ask the user before proceeding.
Ask: Do you want to set up Cloudflare R2 for file storage (images, uploads)?
- Yes — read and follow references/r2-setup.md
- No — skip (can be configured later)
Step 5: Email Sending (Optional)
⛔ STOP — You MUST ask the user before proceeding.
Ask: Do you want to use Cloudflare Email Sending for transactional emails (verification codes, password resets)?
- Yes — read and follow references/email-setup.md
- No — skip (default is Resend, or configure later)
Step 6: Turnstile Bot Protection (Optional)
⛔ STOP — You MUST ask the user before proceeding.
Ask: Do you want to enable Cloudflare Turnstile (CAPTCHA) for login/signup protection?
- Yes — read and follow references/turnstile-setup.md
- No — skip (disabled by default, safe to add later)
Step 7: Deploy to Workers
⛔ STOP — You MUST ask the user before proceeding.
Ask: Do you want to deploy to Cloudflare Workers now, or just finish the local setup?
- Deploy now — read and follow references/workers-deploy.md
- Later — tell the user they can deploy anytime with
cd apps/tanstack-app && pnpm run deploy:cf
Step 8: Summary
After setup is complete, provide a summary of what was configured:
✅ Cloudflare Setup Complete
─────────────────────────────
Template: [tinyship-cf (fast path) / shipeasy (full wizard)]
Frameworks: TanStack Start only [Next/Nuxt removed / kept]
Workers: TanStack Start on Cloudflare Workers
Database: [D1 / Hyperdrive+PG] — configured and verified
Storage: [R2 / skipped]
Email: [Cloudflare Email / skipped]
Turnstile: [enabled / skipped]
Deployment: [deployed to <url> / ready for deploy]
Next steps:
- tinyship-cf: `pnpm dev` for local dev, `pnpm deploy:cf` to deploy
- shipeasy: `cd apps/tanstack-app && pnpm dev:cf` / `pnpm run deploy:cf`
- Use `npx wrangler tail` to view live logs
Reference Files in TinyShip Repo
When executing this skill, read these files from the user's project for context:
apps/tanstack-app/wrangler.jsonc— current Wrangler configapps/tanstack-app/CF-NOTES.md— known Cloudflare pitfallsapps/tanstack-app/.dev.vars.example— local dev vars template (tinyship-cf)env.example— all environment variables (shipeasy only)apps/tanstack-app/vite.config.ts— CF plugin conditional loadingdocs/user-guide/deployment/cloudflare-workers.md— full deployment guideconfig/storage.ts— R2 config structureconfig/email.ts— Email config structureconfig/captcha.ts— Turnstile config structure