tanstack-start_skill

Overview

This skill packages TanStack Start guidance for building full-stack React apps on Cloudflare Workers with TypeScript. It focuses on type-safe routing, server functions, SSR/streaming, and integration with D1, KV, and R2. It also documents migration steps from Vinxi to Vite and prevents nine common deployment and runtime errors.

How this skill works

The content inspects project configuration, routing patterns, server-function usage, Cloudflare bindings, and prerendering logic to surface migration and deployment pitfalls. It provides concrete code snippets, wrangler and Vite config examples, and recommended patterns for database, auth, and file-upload handling. It highlights known limitations and practical workarounds so developers can ship stable SSR apps on Workers.

When to use it

• Starting a new full-stack React app targeting Cloudflare Workers with SSR or streaming.
• Migrating an existing TanStack Start project from Vinxi to Vite (v1.121.0+).
• Integrating D1, KV, or R2 storage into server functions and needing binding examples.
• Troubleshooting prerendering failures, server-function redirects, or auth cookie issues.
• Preventing documented runtime errors and deployment misconfigurations on Workers.

Best practices

• Use @tanstack/react-start@1.138.0+ and the latest Vite plugin; set cloudflare.viteEnvironment = { name: 'ssr' }.
• Add compatibility_flags = ["nodejs_compat"] and main = "@tanstack/react-start/server-entry" in wrangler config.
• Disable prerendering for routes that access Cloudflare bindings or add conditional loader logic to skip DB calls at build time.
• Prefer createIsomorphicFn for client-preserving auth flows and manually forward headers when server-side-only logic is required.
• Avoid relying on Start's automatic formData behavior for large uploads; validate client-side and use R2 multipart or alternative streaming APIs.

Example use cases

• New Vite-based TanStack Start app with SSR and Cloudflare Workers deployment pipelines.
• Migrating an app that used Vinxi: update config files, API route APIs, and entry points.
• Server function that queries D1 and returns user lists while respecting Cloudflare bindings.
• Implementing Better Auth integration using reactStartCookies plugin to handle cookie edge cases.
• CI builds that require remote bindings: configure env variables and avoid .env.local for CI secrets.