Agent Skills: TanStack Start — Deployment

Covers production env-var handling (read process.env per request, never at module scope — Cloudflare injects env at request time so module-level reads are undefined on the edge), plugin ordering (cloudflare() before tanstackStart()), matching start scripts to the build output, React 19 pinning for Bun, and prerendering limits (dynamic $id routes, layout _ routes, and component-less routes are skipped unless linked via crawlLinks).

Includes full vite.config.ts templates per adapter and a complete Cloudflare Workers deploy template, plus a production checklist.

Do NOT use this skill for app data/auth logic (see start-routing-data / start-auth) or for generic Vite config unrelated to Start. </objective>

TanStack Start — Deployment

Agent Workflow (MANDATORY)

Before ANY implementation, spawn in parallel:

1. fuse-ai-pilot:explore-codebase — read vite.config.ts, package.json scripts, existing adapter/wrangler config
2. fuse-ai-pilot:research-expert — verify adapter setup via Context7 /websites/tanstack_start_framework_react
3. mcp__context7__query-docs — confirm tanstackStart plugin + adapter options for the target host

After implementation, run fuse-ai-pilot:sniper.

Overview

| Target | Setup | |--------|-------| | Cloudflare Workers ⭐ | @cloudflare/vite-plugin (viteEnvironment: { name: 'ssr' }) + wrangler.jsonc | | Netlify ⭐ | @netlify/vite-plugin-tanstack-start | | Vercel / Render / Node / Docker / Bun / Railway | Nitro layer (nitro/vite), .output/server/index.mjs | | Static | tanstackStart({ prerender: { enabled: true, crawlLinks }, pages: [{ path }] }) |

Start builds with Vite (or Rsbuild). Most hosts go through Nitro, an agnostic deploy layer; Cloudflare and Netlify have dedicated Vite plugins.

Critical Rules

1. Read env per request — process.env.X inside handlers, NEVER at module scope; Cloudflare injects env at request time, so module reads are undefined on the edge.
2. Cloudflare plugin order — cloudflare({ viteEnvironment: { name: 'ssr' } }) before tanstackStart() in the plugins array.
3. Match start to the build — Nitro output starts with node .output/server/index.mjs; Cloudflare uses wrangler deploy (no node start).
4. React 19 for Bun — pin react/react-dom to >= 19 when deploying on Bun.
5. Prerender excludes dynamics — param routes ($id), layout routes (_), and component-less routes are skipped unless linked with crawlLinks.

Architecture

vite.config.ts        # tanstackStart() + host adapter (cloudflare / netlify / nitro)
wrangler.jsonc        # Cloudflare only — main: @tanstack/react-start/server-entry
package.json          # scripts differ per target (deploy vs start)
.output/server/       # Nitro build output (Node/Vercel/Bun/Railway)

→ See vite-config-adapters.md for every adapter config

Reference Guide

Concepts

| Topic | Reference | Load when | |-------|-----------|-----------| | Build & adapters | build-and-adapters.md | Choosing/configuring a host (Nitro, Vercel, Node, Bun, Railway, Netlify) | | Cloudflare | cloudflare.md | Deploying to Cloudflare Workers | | Prerendering | prerendering.md | Generating static HTML at build time | | Env & checklist | env-and-checklist.md | Production env vars + pre-deploy checklist |

Templates

| Template | When to Use | |----------|-------------| | vite-config-adapters.md | Full vite.config.ts per target + prerender | | cloudflare-deploy.md | Complete Cloudflare Workers setup |

Best Practices

DO

• Confirm the official partner list (Netlify, Render, Cloudflare, Vercel, Railway, Lovable) before hand-rolling config
• Keep secrets in the host's env store; read them per request
• Prerender marketing/blog routes; keep dynamic/auth routes SSR

DON'T

• Read process.env at import time (edge = undefined; bundle leak)
• Mix a Nitro node start script with a Cloudflare build
• Expect $param routes to prerender without crawlLinks