Start BETA - Tracking #2863

SeanCassiere · 2024-11-26T03:10:03Z

SeanCassiere
Nov 26, 2024
Maintainer

Tracking any important changes for TanStack Start during the BETA period.

If you are coming from the ALPHA of TanStack Start, you can see all the breaking changes that were made here - #2403

SeanCassiere · 2024-11-27T08:28:24Z

SeanCassiere
Nov 27, 2024
Maintainer Author

v1.83.0 - Changed export variable renamed from `Route` to `APIRoute`

Important

Breaking change for users of API Routes

We've changed the name of the variable that's picked up by the API handler for routes that have API Routes configured.

// app/routes/api.foo.tsx
import { createAPIFileRoute } from '@tanstack/start/api'

- export const Route = createAPIFileRoute('/api/foo')({
+ export const APIRoute = createAPIFileRoute('/api/foo')({
    GET: () => {
        return new Response('Hello world')
    }
})

0 replies

schiller-manuel · 2025-02-14T22:24:01Z

schiller-manuel
Feb 14, 2025
Maintainer

v1.105.0 - `<HeadContent>` replaces `<Meta>`

<Meta> was replaced by <HeadContent>.
<Scripts> moved into @tanstack/react-router

This is non-breaking, but <Meta> is now deprecated and will be removed later.

 // app/routes/__root.tsx
-import { createRootRoute } from '@tanstack/react-router'
+import { createRootRoute, HeadContent, Scripts } from '@tanstack/react-router'
 import { Outlet } from '@tanstack/react-router'
-import { Meta, Scripts } from '@tanstack/start'
 import * as React from 'react'
 
 export const Route = createRootRoute({
@@ -231,7 +230,7 @@ function RootDocument({ children }: { children: React.ReactNode }) {
   return (
     <html>
       <head>
-        <Meta />
+        <HeadContent />
       </head>
       <body>
         {children}

0 replies

schiller-manuel · 2025-02-25T21:21:20Z

schiller-manuel
Feb 25, 2025
Maintainer

v1.111.10 - renamed package from `@tanstack/start` to `@tanstack/react-start`

@tanstack/start was renamed to @tanstack/react-start.

This is non-breaking, but @tanstack/start is now deprecated and will be removed later.

0 replies

SeanCassiere · 2025-03-11T08:08:56Z

SeanCassiere
Mar 11, 2025
Maintainer Author

⏱️ coming soon, moving from `./app` to `./src`

As part of our Vite + Nitro migration, we'll be changing the default base app directory for TanStack Start, from ./app to ./src, which will be more Vite-native.

If you'd like to opt-in to this behaviour early, you can make these changes, to move from `./app` to `./src`.

Set tsr.appDirectory to ./src in your app.config.ts.

// app.config.ts
import { defineConfig } from '@tanstack/react-start/config'

export default defineConfig({
+	tsr: {
+		appDirectory: './src'
+	}
	// ...
})

If you are using path aliases, change the source from ./app to ./src in your tsconfig.json.

{
	"compilerOptions": {
		"paths": {
-			"~/*": ["app/*"]
+			"~/*": ["./src/*"]
		}
	}
}

If you are using TailwindCSS, change the content source from ./app to ./src in your tailwind.config.js

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
-  content: ['./app/**/*.{js,jsx,ts,tsx}'],
+  content: ['./src/**/*.{js,jsx,ts,tsx}'],
}

Rename the app folder to src.

If you run into any issues, feel free to hop into our Discord server and create a question in the #start-questions channel.

To give you the best 'new user experience', we've already updated the examples (#3712). Documentation changes, shouldn't be too far behind.

This post will be deleted/hidden, once the Vite + Nitro migration has been completed and merged in.

0 replies

SeanCassiere · 2025-05-11T04:34:21Z

SeanCassiere
May 11, 2025
Maintainer Author

v1.121.0

We merged "devinxi" alpha to main. please follow the steps below to upgrade.

Move to the framework adapter

As mentioned earlier in this message, we're moving all released to framework-specific adapters. As such, we'll no longer be publishing/updating the @tanstack/start package.

npm uninstall @tanstack/start
npm install @tanstack/react-start

Migration guide

We've made a few key breaking changes that you'll need to make when upgrading
to v1.121.0.

These changes have been broken down into the large sweeping changes, smaller changes,
and optional ones.

Important

Before going through this guide, make sure that you've backed up your project and have it
committed to version control (like Git) in a working state.

Core Migration

Let's go! 🚅

Swap to Vite

You'll need to remove the vinxi package and install Vite 6+.

npm uninstall vinxi
npm install vite

Update your packages

You'll need to update any of the TanStack Router or Start packages to latest.

# This is not an exhaustive list of packages.
# Look at your `package.json` for the packages you'd need to upgrade.
npm install @tanstack/react-router@latest @tanstack/react-router-devtools@latest
npm install @tanstack/react-start@latest

If you are using SolidJS, swap out the react- prefix for solid-.

Update your `scripts`

You'll need to update the scripts in your package.json to use the Vite dev and build commands.

{
  "scripts": {
    "dev": "vite dev --port 3000",
    "build": "vite build",
    "start": "node .output/server/index.mjs"
  }
}

`app.config.ts` to `vite.config.ts`

TanStack Start is now a Vite plugin. So, register the plugin in a Vite config file and delete app.config.ts.

// vite.config.ts
import { defineConfig } from 'vite'
import tsconfigPaths from 'vite-tsconfig-paths'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'

export default defineConfig({
  plugins: [
    tsconfigPaths(),
    // tailwindcss(), sentry(), ...
    tanstackStart({ /** Add your options here */ })
  ]
})

Rename `app/` to `src/`

We're staying Vite-native. All your source code should be moved from app/ to src/.

mv app src

if you use a path alias in your tsconfig.json, make sure to also update that to src:

 "paths": {
      "@/*": [
        "./src/*"
      ]
    },

You need `src/router.tsx`

You'll need to make sure that you have your createRouter function
exported out of src/router.tsx.

// src/router.tsx
import { createRouter as createTanStackRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export function createRouter() {
  const router = createTanStackRouter({
    routeTree,
    scrollRestoration: true,
  })

  return router
}

declare module '@tanstack/react-router' {
  interface Register {
    router: ReturnType<typeof createRouter>
  }
}

Delete `src/client.tsx` and `src/ssr.tsx`

If you did NOT customize your src/client.tsx and src/ssr.tsx files, then you can delete them.

rm -rf src/client.tsx
rm -rf src/ssr.tsx

However, if you did customize the these files, like installing when installing the Clerk adapter,
then you'll need to rename the src/ssr.tsx file to src/server.tsx.

mv src/ssr.tsx src/server.tsx

If you are using a custom server.tsx entry, then the overall structure of the file (including
the default export) should look something similar to this.

// src/server.tsx
import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server'

import { createRouter } from './router'

export default createStartHandler({
  createRouter,
})(defaultStreamHandler)

Devinxi - Changes to your TanStack Start config

TODO: List out all the changes

We've moved around some of the options in the TanStack Start config.

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'

export default defineConfig({
  plugins: [
    tanstackStart({ 
	    // The changes are...
	  })
  ]
})

Devinxi - Migrating from API Routes to Server Routes

API routes have seen a huge improvement and we're now calling them "Server Routes".

First, delete the src/api.ts entry handler.

rm -rf src/api.ts

In your API routes files, you'll need to make the following changes to turn them into Server Routes.

// src/routes/api/users.tsx
import { json } from '@tanstack/react-start'
- import { createAPIFileRoute } from '@tanstack/react-start/api'
import { fetchUsers } from '../../utils/users'

- export const APIRoute = createAPIFileRoute('/api/users')({
+ export const ServerRoute = createServerFileRoute().methods({
  GET: async ({ request, params }) => {
    console.info('Fetching users... @', request.url)
    const users = await fetchUsers()
    // You can now call Server Functions from here 🥳
    return json(users)
  },
})

You more easily find these routes by search for the imports from @tanstack/react-start/api.

Not migrating at this time

If you decide that right now is not the appropriate time to migrate you will need to pin your versions of @tanstack/react-start (as well as several other related libraries). We have built a simple helper function into create-start-app to help you with this process: npx create-start-app@latest pin-versions. Simply execute that command in your application's root directory and the command will make the necessary adjustments to your package.json file. Then you can remove the node_modules directory as well as package lock files, and re-install and you should be able to continue with your development and upgrade when you choose.

0 replies

schiller-manuel · 2025-07-09T21:33:53Z

schiller-manuel
Jul 9, 2025
Maintainer

⏱️ coming soon, no more autoconfiguring of solid/react vite plugin

TanStack Start will soon stop auto-configuring React/Solid Vite plugins.
You’ll get full control - choose @vitejs/plugin-react, @vitejs/plugin-react-oxc, etc.

You can already now experience that with customViteReactPlugin: true

0 replies

schiller-manuel · 2025-07-11T23:33:33Z

schiller-manuel
Jul 11, 2025
Maintainer

v1.127.3 - Changed `router.isShell` to `router.isShell()`

Important

Breaking change for users of SPA mode

We've changed the shell detection during SPA mode build from a variable router.isShell to a function invocation router.isShell()

0 replies

schiller-manuel · 2025-08-08T20:47:14Z

schiller-manuel
Aug 8, 2025
Maintainer

v1.131.0 - renamed query integration to `@tanstack/react-router-ssr-query`

this also changes the API of that package

see https://tanstack.com/router/latest/docs/integrations/query

0 replies

schiller-manuel · 2025-08-08T21:42:27Z

schiller-manuel
Aug 8, 2025
Maintainer

Start RC - v1.132

deployment

Start is not coupled with Nitro anymore by default.
You can use a nitro vite plugin to get the same deployment behavior as with beta:

import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { defineConfig } from 'vite'
import viteReact from '@vitejs/plugin-react'
import { nitroV2Plugin } from '@tanstack/nitro-v2-vite-plugin'

export default defineConfig({
  plugins: [
    tanstackStart(),
    nitroV2Plugin(/* 
      // nitro config goes here, e.g.
      { target: 'node-server' }
    */),
    viteReact(),
  ],
})

The documentation contains a variety of deployment configurations that are now possible (with and without nitro):

https://tanstack.com/start/latest/docs/framework/react/hosting

minimum node version

minimum node version was set to 22.12

minimum vite version 7

make sure to update vite to v7

no more autoconfiguring of solid/react vite plugin

add the react / solid plugin of your choice to your vite config:

import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [
    tanstackStart(),
    viteReact(),
  ],
})

tanstackStart vite plugin config changes

tsr prop was renamed to router

export default defineConfig({
       projects: ['./tsconfig.json'],
     }),
     tanstackStart({
-      tsr: {
+      router: {
         virtualRouteConfig: './routes.ts',
       },
     }),

tsr.srcDirectory prop was moved up to top level

export default defineConfig({
   },
   plugins: [
     tanstackStart({
-      tsr: {
-        srcDirectory: './src/app',
-      },
+      srcDirectory: './src/app',
     }),
   ],
 })

`validator` renamed to `inputValidator`

export const greetUser = createServerFn({ method: 'GET' })
-  .validator((data: { name: string }) => data)
+  .inputValidator((data: { name: string }) => data)
  .handler(async ({ data }) => {
    return `Hello, ${data.name}!`
  })

static server functions moved into a middleware

import { createServerFn } from '@tanstack/react-start'
import { staticFunctionMiddleware } from '@tanstack/start-static-server-functions'

const myServerFn = createServerFn({ method: 'GET' }).middleware([staticFunctionMiddleware]).handler(async () => {
  return 'Hello, world!'
})

Ensure that staticFunctionMiddleware is the final middleware!

renaming

getWebRequest renamed to getRequest
getHeaders renamed to getRequestHeaders
getHeader renamed to getRequestHeader
setHeaders renamed to setResponseHeaders
setHeader renamed to setResponseHeader
parseCookies renamed to getCookies
serverOnly renamed to createServerOnlyFn
clientOnly renamed to createClientOnlyFn

router.tsx

export was renamed to getRouter:

- export function createRouter() {
+ export function getRouter() {
     return createRouter({
        routeTree,
        // ...
     })
  }

module declaration is now autogenerated in routeTree.gen.ts

Server functions

response modes have been removed. just return a Response if you want to return a raw Response.

Server request entry point ("server.ts") signature changed:

The entry point must conform to the following interface:

export default {
  fetch(req: Request): Promise<Response> {
    // ...
  },
}

unified route tree for server routes

- import { createServerFileRoute } from '@tanstack/react-start/server'
+ import { createFileRoute } from '@tanstack/react-router'

- export const ServerRoute = createServerFileRoute('/hello').methods({
+ export const Route = createFileRoute('/hello')({
+  server: {
+    handlers: {
      GET: async ({ request }) => {
        return new Response('Hello, World!')
      },
+   },
+  },
})

global middleware

registerGlobalMiddlware was removed.
please read the docs about global middleware: https://tanstack.com/start/latest/docs/framework/react/middleware#global-middleware

custom client entrypoint client.tsx

-import { StartClient } from '@tanstack/react-start'
+import { StartClient } from '@tanstack/react-start/client'
import { StrictMode } from 'react'
import { hydrateRoot } from 'react-dom/client'

hydrateRoot(
  document,
  <StrictMode>
-    <StartClient router={router} />
+   <StartClient />
  </StrictMode>,
)

other changes

removed deprecated Meta and Scripts exports from solid/react start

0 replies

Uh oh!

Start BETA - Tracking #2863

Uh oh!

SeanCassiere Nov 26, 2024 Maintainer

Replies: 9 comments

Uh oh!

Uh oh!

SeanCassiere Nov 27, 2024 Maintainer Author

v1.83.0 - Changed export variable renamed from Route to APIRoute

Uh oh!

Uh oh!

schiller-manuel Feb 14, 2025 Maintainer

v1.105.0 - <HeadContent> replaces <Meta>

Uh oh!

Uh oh!

schiller-manuel Feb 25, 2025 Maintainer

v1.111.10 - renamed package from @tanstack/start to @tanstack/react-start

Uh oh!

SeanCassiere Mar 11, 2025 Maintainer Author

⏱️ coming soon, moving from ./app to ./src

Uh oh!

Uh oh!

SeanCassiere May 11, 2025 Maintainer Author

v1.121.0

Move to the framework adapter

Migration guide

Core Migration

Swap to Vite

Update your scripts

app.config.ts to vite.config.ts

Rename app/ to src/

You need src/router.tsx

Delete src/client.tsx and src/ssr.tsx

Devinxi - Changes to your TanStack Start config

Devinxi - Migrating from API Routes to Server Routes

Not migrating at this time

Uh oh!

schiller-manuel Jul 9, 2025 Maintainer

⏱️ coming soon, no more autoconfiguring of solid/react vite plugin

Uh oh!

Uh oh!

schiller-manuel Jul 11, 2025 Maintainer

v1.127.3 - Changed router.isShell to router.isShell()

Uh oh!

Uh oh!

schiller-manuel Aug 8, 2025 Maintainer

v1.131.0 - renamed query integration to @tanstack/react-router-ssr-query

Uh oh!

Uh oh!

schiller-manuel Aug 8, 2025 Maintainer

Start RC - v1.132

deployment

minimum node version

minimum vite version 7

no more autoconfiguring of solid/react vite plugin

tanstackStart vite plugin config changes

validator renamed to inputValidator

static server functions moved into a middleware

renaming

router.tsx

Server functions

Server request entry point ("server.ts") signature changed:

unified route tree for server routes

global middleware

custom client entrypoint client.tsx

other changes

SeanCassiere
Nov 26, 2024
Maintainer

SeanCassiere
Nov 27, 2024
Maintainer Author

v1.83.0 - Changed export variable renamed from `Route` to `APIRoute`

schiller-manuel
Feb 14, 2025
Maintainer

v1.105.0 - `<HeadContent>` replaces `<Meta>`

schiller-manuel
Feb 25, 2025
Maintainer

v1.111.10 - renamed package from `@tanstack/start` to `@tanstack/react-start`

SeanCassiere
Mar 11, 2025
Maintainer Author

⏱️ coming soon, moving from `./app` to `./src`

SeanCassiere
May 11, 2025
Maintainer Author

Update your `scripts`

`app.config.ts` to `vite.config.ts`

Rename `app/` to `src/`

You need `src/router.tsx`

Delete `src/client.tsx` and `src/ssr.tsx`

schiller-manuel
Jul 9, 2025
Maintainer

schiller-manuel
Jul 11, 2025
Maintainer

v1.127.3 - Changed `router.isShell` to `router.isShell()`

schiller-manuel
Aug 8, 2025
Maintainer

v1.131.0 - renamed query integration to `@tanstack/react-router-ssr-query`

schiller-manuel
Aug 8, 2025
Maintainer

`validator` renamed to `inputValidator`