iTranslated by AI
Migrating the OpenAI ChatKit Starter App to TanStack Start
Overview
I've been interested in TanStack Start for a while, and now that it's finally reached RC, I was thinking about starting something with it. Around the same time, OpenAI released a ChatKit starter app built with Next.js, so I thought, why not migrate that starter app to TanStack Start? Here's a record of that effort.
Original repository:
Migration Result
The migrated result is available here:
Migration Steps
Migrating According to the Official Guide
First, I followed the migration guide provided by TanStack Start.
After that, I changed environment variables from NEXT_PUBLIC_* to import.meta.env.VITE_*.
Since the app was relatively small, the migration was completed in about an hour.
Additional Setup for Start
After migration, I performed setup specific to TanStack Start. Based on the sample app provided by TanStack Start, I introduced devtools, switched ESLint from Next.js to TanStack Start, and shifted the directory structure from Next.js to one suitable for TanStack Start.
Template I referenced:
Refactoring Complex Components
One thing that bothered me in the original repository was that the component responsible for displaying the chat screen seemed unnecessarily complex, so I refactored it.
Original:
My refactored version:
In this refactoring, the ChatKit component had a part that retrieves authentication information from the server side, and since I really wanted to use TanStack Query for that, it took a bit of extra time.
Introducing the Nitro V2 Plugin
TanStack Start uses a toolkit called Nitro. This allows TanStack Start to be deployed on various hosting services such as Cloudflare, AWS Amplify, Netlify, etc.
At the recent ViteConf, Nitro V3 was announced, but since V3 is still in alpha, it's reportedly safer to take steps to continue using V2. Therefore, I followed the steps to introduce the V2 plugin.
Stumbling Points
CSS Not Loading Properly
When the app was initially loaded, the application rendered without any CSS styles applied. In short, I needed to load the CSS in __root.tsx, so I fixed that.
Points of Concern
Lack of JSDoc
JSDoc was not displayed for functions and parameters, leading to several questions like "Why is this necessary?" or "What's the difference between this and that?" For example:
- When introducing TanStack Query, the
setupRouterSsrQueryIntegrationfunction defined inrouter.tsxhad no JSDoc, so I couldn't understand its necessity (likely needed to use TanStack Query in loaders?). - The difference between using
<Outlet />in__root.tsxand usingshellComponent. I couldn't find documentation for this even after searching the official docs.
Pattern using <Outlet />:
Pattern using shellComponent:
I felt there might be opportunities to contribute by adding documentation for these points.
Impressions
I stumbled on the CSS loading issue, but apart from that, the migration went smoothly. I'm looking forward to RSC being introduced in TanStack Start in the future. Additionally, I think I could gain more insights by migrating a more complex Next.js app to TanStack Start, so I'll work on that when I have time. Also, since features implemented in Nitro V3 are likely to become available in TanStack Start as-is, I plan to explore that as well.
Discussion