iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
🕌

Migrating the OpenAI ChatKit Starter App to TanStack Start

に公開
2025/10/21

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:
https://github.com/openai/openai-chatkit-starter-app

Migration Result

The migrated result is available here:
https://github.com/HirotoShioi/openai-chatkit-tanstack-starter-app

Migration Steps

Migrating According to the Official Guide

First, I followed the migration guide provided by TanStack Start.
https://tanstack.com/start/latest/docs/framework/react/migrate-from-next-js

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:
https://github.com/TanStack/router/tree/main/examples/react/start-basic-react-query

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:
https://github.com/openai/openai-chatkit-starter-app/blob/main/components/ChatKitPanel.tsx

My refactored version:
https://github.com/HirotoShioi/openai-chatkit-tanstack-starter-app/blob/main/src/components/ChatKitPanel.tsx

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.
https://nitro.build/

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.
https://tanstack.com/start/latest/docs/framework/react/guide/hosting#nitro

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.
https://github.com/HirotoShioi/openai-chatkit-tanstack-starter-app/pull/5/commits/2ca44522a7a5c9a8d2cfacb2aa13a3031002da35

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 setupRouterSsrQueryIntegration function defined in router.tsx had no JSDoc, so I couldn't understand its necessity (likely needed to use TanStack Query in loaders?).
  • The difference between using <Outlet /> in __root.tsx and using shellComponent. I couldn't find documentation for this even after searching the official docs.

Pattern using <Outlet />:
https://github.com/HirotoShioi/openai-chatkit-tanstack-starter-app/blob/main/src/routes/__root.tsx#L32

Pattern using shellComponent:
https://github.com/TanStack/router/blob/main/examples/react/start-basic/src/routes/__root.tsx#L62

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