Next.js Out, Tanstack Start In: T3 Chat Engineers Detail High-Stakes Migration

T3 Chat, the popular AI chat application, has completed a significant architectural migration, transitioning its core platform from Next.js to Tanstack Start. The move, spearheaded by engineer Julius and involving a massive 14,000 lines added and 10,000 lines removed, was driven by the need for a framework better suited to T3 Chat’s client-side focused Single Page Application (SPA) architecture. Initially, Next.js was leveraged as a convenient bundler for a React client and TypeScript server, allowing for easy deployment, server-client synchronization, and adherence to ‘boring tech’ principles. However, this approach necessitated extensive hacks, including brute-forcing React Router for client-side navigation and custom handling for TRPC endpoints, which ultimately proved unsustainable for long-term scalability and developer experience. The journey to Tanstack Start involved explorations of alternatives like Remix and a custom Vite + Hono setup, encountering challenges with Cloudflare deployments and bundle size limits before settling on the Tanstack ecosystem, which had been under consideration since February.

While Tanstack Start offers type-safe routing and a more flexible foundation, the migration was not without its hurdles. T3 Chat engineers encountered critical issues, including ‘fetch failed’ and ‘too many files’ errors during Vercel deployments, attributed to Tanstack’s lazy bundling mechanisms at scale. The solution involved integrating Nitro, a server-side runtime from the Nuxt ecosystem, to handle API routes independently, requiring patches to Tanstack Start’s core to expose necessary event bindings. This hybrid approach allowed T3 Chat to preserve crucial deployment synchronization while optimizing Vercel Fluid Compute utilization. Despite these challenges, the team reports a cleaner codebase, improved debugging, and enhanced ownership of implementation details. This pragmatic shift underscores a broader industry lesson: there is no universal ‘best’ framework, and large-scale applications inevitably involve unique technical challenges and ‘hacks’ that necessitate tailored solutions aligning with team needs and product goals.