Deployment Guide

Overview & Architecture

How TanStack Ship runs on Cloudflare Workers, D1, R2, KV, and Queues.

TanStack Ship is built on TanStack Start. Production runs on Cloudflare Workers, with data and async work handled by Cloudflare-native services.

Important

Pushing to GitHub does not deploy production. Release locally with pnpm run deploy (not pnpm deploy).

Platform Architecture

ComponentRoleConfig
WorkersSSR, API, Cronwrangler.jsonc
D1Users, billing, blog, attributiond1_databases
R2Uploads, media assetsr2_buckets + env vars
KVShort-link slug mappingkv_namespaces
QueuesEmail campaigns, workflowsqueues

Prerequisites

ToolVersion
Node.js20+
pnpm10+
Wrangler4.x
Cloudflare accountWorkers, D1, R2, KV, Queues enabled

One-time login:

bash
pnpm wrangler login

Recommended Reading Order

  1. Local Development — install, .dev.vars, local D1
  2. Cloudflare Resources — create D1/R2/KV/Queues
  3. Environment Variables — full reference
  4. Secrets & API Keys — OAuth, Stripe, etc.
  5. Integrations — Resend step-by-step
  6. Production Deploy — build and release
  7. Verify & Troubleshoot — launch checklist

Local vs Production

DimensionLocalProduction
Env file.dev.varswrangler secret + vars
Databasepnpm db:migrate:localpnpm db:migrate:remote
Client VITE_*.dev.vars / shellInjected at build; redeploy after changes
BindingsVite mocks cloudflare:workerswrangler.jsonc bindings

Good to know

During local dev, Vite reads .dev.vars and mocks the Workers environment (Stripe, R2, PostHog, etc.) so you don't need remote Cloudflare on every run.