Merge branch 'main' into start-clerk-basic-solid

Author: brenelz

docs/start/config.json

@@ -338,6 +338,10 @@
               "label": "Basic + Supabase",
               "to": "framework/solid/examples/start-basic-supabase"
             },
+            {
+              "label": "Bare + Convex + Better Auth",
+              "to": "framework/solid/examples/start-convex-better-auth"
+            },
             {
               "label": "Cloudflare Vite Plugin",
               "to": "framework/solid/examples/start-basic-cloudflare"

docs/start/framework/react/guide/execution-model.md

@@ -98,6 +98,31 @@ function Analytics() {
 }
 ```
 
+#### useHydrated Hook
+
+For more granular control over hydration-dependent behavior, use the `useHydrated` hook. It returns a boolean indicating whether the client has been hydrated:
+
+```tsx
+import { useHydrated } from '@tanstack/react-router'
+
+function TimeZoneDisplay() {
+  const hydrated = useHydrated()
+  const timeZone = hydrated
+    ? Intl.DateTimeFormat().resolvedOptions().timeZone
+    : 'UTC'
+
+  return <div>Your timezone: {timeZone}</div>
+}
+```
+
+**Behavior:**
+
+- **During SSR**: Always returns `false`
+- **First client render**: Returns `false`
+- **After hydration**: Returns `true` (and stays `true` for all subsequent renders)
+
+This is useful when you need to conditionally render content based on client-side data (like browser timezone, locale, or localStorage) while providing a sensible fallback for server rendering.
+
 ### Environment-Specific Implementations
 
 ```tsx

docs/start/framework/react/guide/hosting.md

@@ -18,7 +18,7 @@ However, since hosting is one of the most crucial aspects of your application's
 
 Once you've chosen a deployment target, you can follow the deployment guidelines below to deploy your TanStack Start application to the hosting provider of your choice:
 
-- [`cloudflare-workers`](#cloudflare-workers): Deploy to Cloudflare Workers
+- [`cloudflare-workers`](#cloudflare-workers--official-partner): Deploy to Cloudflare Workers
 - [`netlify`](#netlify): Deploy to Netlify
 - [`nitro`](#nitro): Deploy using Nitro
 - [`vercel`](#vercel): Deploy to Vercel

docs/start/framework/solid/guide/execution-model.md

@@ -98,6 +98,30 @@ function Analytics() {
 }
 ```
 
+#### useHydrated Hook
+
+For more granular control over hydration-dependent behavior, use the `useHydrated` hook. It returns an accessor (signal) indicating whether the client has been hydrated:
+
+```tsx
+import { useHydrated } from '@tanstack/solid-router'
+
+function TimeZoneDisplay() {
+  const hydrated = useHydrated()
+  const timeZone = () =>
+    hydrated() ? Intl.DateTimeFormat().resolvedOptions().timeZone : 'UTC'
+
+  return <div>Your timezone: {timeZone()}</div>
+}
+```
+
+**Behavior:**
+
+- **During SSR**: Always returns `false`
+- **First client render**: Returns `false`
+- **After hydration**: Returns `true` (and stays `true` for all subsequent renders)
+
+This is useful when you need to conditionally render content based on client-side data (like browser timezone, locale, or localStorage) while providing a sensible fallback for server rendering.
+
 ### Environment-Specific Implementations
 
 ```tsx

e2e/react-router/basic-react-query-file-based/src/routeTree.gen.ts

@@ -12,10 +12,10 @@ import { Route as rootRouteImport } from './routes/__root'
 import { Route as PostsRouteImport } from './routes/posts'
 import { Route as LayoutRouteImport } from './routes/_layout'
 import { Route as IndexRouteImport } from './routes/index'
-import { Route as TransitionIndexRouteImport } from './routes/transition/index'
 import { Route as PostsIndexRouteImport } from './routes/posts.index'
 import { Route as PostsPostIdRouteImport } from './routes/posts.$postId'
 import { Route as LayoutLayout2RouteImport } from './routes/_layout/_layout-2'
+import { Route as TransitionCountQueryRouteImport } from './routes/transition/count/query'
 import { Route as LayoutLayout2LayoutBRouteImport } from './routes/_layout/_layout-2/layout-b'
 import { Route as LayoutLayout2LayoutARouteImport } from './routes/_layout/_layout-2/layout-a'
 
@@ -33,11 +33,6 @@ const IndexRoute = IndexRouteImport.update({
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
-const TransitionIndexRoute = TransitionIndexRouteImport.update({
-  id: '/transition/',
-  path: '/transition/',
-  getParentRoute: () => rootRouteImport,
-} as any)
 const PostsIndexRoute = PostsIndexRouteImport.update({
   id: '/',
   path: '/',
@@ -52,6 +47,11 @@ const LayoutLayout2Route = LayoutLayout2RouteImport.update({
   id: '/_layout-2',
   getParentRoute: () => LayoutRoute,
 } as any)
+const TransitionCountQueryRoute = TransitionCountQueryRouteImport.update({
+  id: '/transition/count/query',
+  path: '/transition/count/query',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const LayoutLayout2LayoutBRoute = LayoutLayout2LayoutBRouteImport.update({
   id: '/layout-b',
   path: '/layout-b',
@@ -68,17 +68,17 @@ export interface FileRoutesByFullPath {
   '/posts': typeof PostsRouteWithChildren
   '/posts/$postId': typeof PostsPostIdRoute
   '/posts/': typeof PostsIndexRoute
-  '/transition': typeof TransitionIndexRoute
   '/layout-a': typeof LayoutLayout2LayoutARoute
   '/layout-b': typeof LayoutLayout2LayoutBRoute
+  '/transition/count/query': typeof TransitionCountQueryRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/posts/$postId': typeof PostsPostIdRoute
   '/posts': typeof PostsIndexRoute
-  '/transition': typeof TransitionIndexRoute
   '/layout-a': typeof LayoutLayout2LayoutARoute
   '/layout-b': typeof LayoutLayout2LayoutBRoute
+  '/transition/count/query': typeof TransitionCountQueryRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
@@ -88,9 +88,9 @@ export interface FileRoutesById {
   '/_layout/_layout-2': typeof LayoutLayout2RouteWithChildren
   '/posts/$postId': typeof PostsPostIdRoute
   '/posts/': typeof PostsIndexRoute
-  '/transition/': typeof TransitionIndexRoute
   '/_layout/_layout-2/layout-a': typeof LayoutLayout2LayoutARoute
   '/_layout/_layout-2/layout-b': typeof LayoutLayout2LayoutBRoute
+  '/transition/count/query': typeof TransitionCountQueryRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
@@ -99,17 +99,17 @@ export interface FileRouteTypes {
     | '/posts'
     | '/posts/$postId'
     | '/posts/'
-    | '/transition'
     | '/layout-a'
     | '/layout-b'
+    | '/transition/count/query'
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
     | '/posts/$postId'
     | '/posts'
-    | '/transition'
     | '/layout-a'
     | '/layout-b'
+    | '/transition/count/query'
   id:
     | '__root__'
     | '/'
@@ -118,16 +118,16 @@ export interface FileRouteTypes {
     | '/_layout/_layout-2'
     | '/posts/$postId'
     | '/posts/'
-    | '/transition/'
     | '/_layout/_layout-2/layout-a'
     | '/_layout/_layout-2/layout-b'
+    | '/transition/count/query'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
   LayoutRoute: typeof LayoutRouteWithChildren
   PostsRoute: typeof PostsRouteWithChildren
-  TransitionIndexRoute: typeof TransitionIndexRoute
+  TransitionCountQueryRoute: typeof TransitionCountQueryRoute
 }
 
 declare module '@tanstack/react-router' {
@@ -153,13 +153,6 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/transition/': {
-      id: '/transition/'
-      path: '/transition'
-      fullPath: '/transition'
-      preLoaderRoute: typeof TransitionIndexRouteImport
-      parentRoute: typeof rootRouteImport
-    }
     '/posts/': {
       id: '/posts/'
       path: '/'
@@ -181,6 +174,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LayoutLayout2RouteImport
       parentRoute: typeof LayoutRoute
     }
+    '/transition/count/query': {
+      id: '/transition/count/query'
+      path: '/transition/count/query'
+      fullPath: '/transition/count/query'
+      preLoaderRoute: typeof TransitionCountQueryRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/_layout/_layout-2/layout-b': {
       id: '/_layout/_layout-2/layout-b'
       path: '/layout-b'
@@ -239,7 +239,7 @@ const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
   LayoutRoute: LayoutRouteWithChildren,
   PostsRoute: PostsRouteWithChildren,
-  TransitionIndexRoute: TransitionIndexRoute,
+  TransitionCountQueryRoute: TransitionCountQueryRoute,
 }
 export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)

e2e/react-router/basic-react-query-file-based/src/routes/transition/index.tsx renamed to e2e/react-router/basic-react-query-file-based/src/routes/transition/count/query.tsx

@@ -1,5 +1,5 @@
 import { Link, createFileRoute } from '@tanstack/react-router'
-import { Suspense, useMemo } from 'react'
+import { Suspense } from 'react'
 import { queryOptions, useQuery } from '@tanstack/react-query'
 import { z } from 'zod'
 
@@ -12,12 +12,12 @@ const doubleQueryOptions = (n: number) =>
     queryKey: ['transition-double', n],
     queryFn: async () => {
       await new Promise((resolve) => setTimeout(resolve, 1000))
-      return n * 2
+      return { n, double: n * 2 }
     },
     placeholderData: (oldData) => oldData,
   })
 
-export const Route = createFileRoute('/transition/')({
+export const Route = createFileRoute('/transition/count/query')({
   validateSearch: searchSchema,
   loader: ({ context: { queryClient }, location }) => {
     const { n } = searchSchema.parse(location.search)
@@ -37,15 +37,17 @@ function TransitionPage() {
         <Link
           data-testid="increase-button"
           className="border bg-gray-50 px-3 py-1"
-          from="/transition"
+          from="/transition/count/query"
           search={(s) => ({ n: s.n + 1 })}
         >
           Increase
         </Link>
 
         <div className="mt-2">
-          <div data-testid="n-value">n: {search.n}</div>
-          <div data-testid="double-value">double: {doubleQuery.data}</div>
+          <div data-testid="n-value">n: {doubleQuery.data?.n}</div>
+          <div data-testid="double-value">
+            double: {doubleQuery.data?.double}
+          </div>
         </div>
       </div>
     </Suspense>

e2e/react-router/basic-react-query-file-based/tests/transition.spec.ts

@@ -1,37 +1,95 @@
 import { expect, test } from '@playwright/test'
 
-test('react-query transitions keep previous data during navigation', async ({
+test('transitions/count/query should keep old values visible during navigation', async ({
   page,
 }) => {
-  await page.goto('/transition')
+  await page.goto('/transition/count/query')
 
   await expect(page.getByTestId('n-value')).toContainText('n: 1')
   await expect(page.getByTestId('double-value')).toContainText('double: 2')
 
-  const bodySnapshots: Array<string> = []
+  const bodyTexts: Array<string> = []
 
-  const interval = setInterval(async () => {
+  const pollInterval = setInterval(async () => {
     const text = await page
       .locator('body')
       .textContent()
       .catch(() => '')
-    if (text) bodySnapshots.push(text)
+    if (text) bodyTexts.push(text)
   }, 50)
 
-  await page.getByTestId('increase-button').click()
+  // 1 click
+
+  page.getByTestId('increase-button').click()
+
+  await expect(page.getByTestId('n-value')).toContainText('n: 1', {
+    timeout: 2_000,
+  })
+  await expect(page.getByTestId('double-value')).toContainText('double: 2', {
+    timeout: 2_000,
+  })
 
   await page.waitForTimeout(200)
 
-  clearInterval(interval)
+  await expect(page.getByTestId('n-value')).toContainText('n: 2', {
+    timeout: 2000,
+  })
+  await expect(page.getByTestId('double-value')).toContainText('double: 4', {
+    timeout: 2000,
+  })
+
+  // 2 clicks
+
+  page.getByTestId('increase-button').click()
+  page.getByTestId('increase-button').click()
 
   await expect(page.getByTestId('n-value')).toContainText('n: 2', {
-    timeout: 2_000,
+    timeout: 2000,
   })
   await expect(page.getByTestId('double-value')).toContainText('double: 4', {
-    timeout: 2_000,
+    timeout: 2000,
+  })
+
+  await page.waitForTimeout(200)
+
+  await expect(page.getByTestId('n-value')).toContainText('n: 4', {
+    timeout: 2000,
+  })
+  await expect(page.getByTestId('double-value')).toContainText('double: 8', {
+    timeout: 2000,
+  })
+
+  // 3 clicks
+
+  page.getByTestId('increase-button').click()
+  page.getByTestId('increase-button').click()
+  page.getByTestId('increase-button').click()
+
+  await expect(page.getByTestId('n-value')).toContainText('n: 4', {
+    timeout: 2000,
   })
+  await expect(page.getByTestId('double-value')).toContainText('double: 8', {
+    timeout: 2000,
+  })
+
+  await page.waitForTimeout(200)
+
+  await expect(page.getByTestId('n-value')).toContainText('n: 7', {
+    timeout: 2000,
+  })
+  await expect(page.getByTestId('double-value')).toContainText('double: 14', {
+    timeout: 2000,
+  })
+
+  clearInterval(pollInterval)
 
-  const sawLoading = bodySnapshots.some((text) => text.includes('Loading...'))
+  // With proper transitions, old values should remain visible until new ones arrive
+  const hasLoadingText = bodyTexts.some((text) => text.includes('Loading...'))
 
-  expect(sawLoading).toBeFalsy()
+  if (hasLoadingText) {
+    throw new Error(
+      'FAILED: "Loading..." appeared during navigation. ' +
+        'Solid Router should use transitions to keep old values visible.',
+    )
+  }
 })

e2e/react-start/basic-react-query/package.json

@@ -21,7 +21,8 @@
     "react-dom": "^19.0.0",
     "redaxios": "^0.5.1",
     "tailwind-merge": "^2.6.0",
-    "vite": "^7.1.7"
+    "vite": "^7.1.7",
+    "zod": "^4.1.12"
   },
   "devDependencies": {
     "@playwright/test": "^1.50.1",