TanstackTemplate Docs

This documentation is for teams copying the TanstackTemplate source into a new product. It explains the reusable Cloudflare/TanStack architecture, the safe adoption order, the first customization pass, and the deploy gates needed before traffic goes live.

The current repository contains one concrete implementation of the template: an AI media SaaS built with TanStack Start, Cloudflare Workers, D1, R2, Better Auth, entitlement checks, provider adapters, and release-evidence tooling. Treat that implementation as a working source example, not as the product identity your downstream app must keep.

Use this docs set in this order:

1. Read Quick Start to run the template locally before changing identity.
2. Read Run Modes to choose between local development, local AI preview, staging, and production cutover.
3. Read Adoption Overview before copying the source into a second product.
4. Fill an Adoption Manifest before changing Cloudflare resources or public product identity.
5. Use First Files To Touch for the first controlled customization pass.
6. Use Quick Deploy when you need a real Cloudflare staging proof.
7. Use Deploy Troubleshooting when a preflight, deploy, smoke, or custom-domain step fails.

Template Shape

The intended stack is Cloudflare-first:

• TanStack Start application on Cloudflare Workers.
• D1 for app data, auth/session fallback tables, workspaces, upgrades, and usage or metering records.
• R2 for private user assets and generated outputs behind app-owned proxy routes.
• Workers AI as the default first-party AI runtime when the product needs AI.
• Optional external providers through product-local adapters.
• Better Auth for account sessions, with demo-auth still available for controlled staging smoke while a product is being hardened.
• Manual upgrade request flow and operator-assisted plan activation as the first billing shape.
• Release evidence, smoke tests, and production cutover checks as part of the template, not an afterthought.

What To Replace

A copied product must replace product identity, Cloudflare resource names, secrets, smoke URLs, package names, landing proof, provider choices, safety posture, DNS, custom-domain routing, and legal/commercial handoff before production traffic is approved.

The source implementation can keep its own vertical package names while it serves as a working example. Downstream products should not expose those names to users, Cloudflare resources, GitHub Actions, or public documentation.