fix(solid-router): hydrate route error components consistently

.changeset/solid-error-hydration.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/solid-router': patch
+---
+
+Render route match errors at a consistent boundary position during SSR and hydration so error components remain interactive.

e2e/solid-start/query-integration/src/routeTree.gen.ts

@@ -10,6 +10,7 @@
 
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as IndexRouteImport } from './routes/index'
+import { Route as ErrorComponentHydrationRouteImport } from './routes/error-component-hydration'
 import { Route as UseQueryRouteImport } from './routes/useQuery'
 import { Route as LoaderFetchQueryTypeRouteImport } from './routes/loader-fetchQuery/$type'
 import { Route as NotFoundReloadIdRouteImport } from './routes/not-found-reload.$id'
@@ -19,6 +20,11 @@ const IndexRoute = IndexRouteImport.update({
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ErrorComponentHydrationRoute = ErrorComponentHydrationRouteImport.update({
+  id: '/error-component-hydration',
+  path: '/error-component-hydration',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const UseQueryRoute = UseQueryRouteImport.update({
   id: '/useQuery',
   path: '/useQuery',
@@ -37,19 +43,22 @@ const NotFoundReloadIdRoute = NotFoundReloadIdRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/error-component-hydration': typeof ErrorComponentHydrationRoute
   '/useQuery': typeof UseQueryRoute
   '/loader-fetchQuery/$type': typeof LoaderFetchQueryTypeRoute
   '/not-found-reload/$id': typeof NotFoundReloadIdRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/error-component-hydration': typeof ErrorComponentHydrationRoute
   '/useQuery': typeof UseQueryRoute
   '/loader-fetchQuery/$type': typeof LoaderFetchQueryTypeRoute
   '/not-found-reload/$id': typeof NotFoundReloadIdRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/error-component-hydration': typeof ErrorComponentHydrationRoute
   '/useQuery': typeof UseQueryRoute
   '/loader-fetchQuery/$type': typeof LoaderFetchQueryTypeRoute
   '/not-found-reload/$id': typeof NotFoundReloadIdRoute
@@ -58,21 +67,29 @@ export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
     | '/'
+    | '/error-component-hydration'
     | '/useQuery'
     | '/loader-fetchQuery/$type'
     | '/not-found-reload/$id'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/useQuery' | '/loader-fetchQuery/$type' | '/not-found-reload/$id'
+  to:
+    | '/'
+    | '/error-component-hydration'
+    | '/useQuery'
+    | '/loader-fetchQuery/$type'
+    | '/not-found-reload/$id'
   id:
     | '__root__'
     | '/'
+    | '/error-component-hydration'
     | '/useQuery'
     | '/loader-fetchQuery/$type'
     | '/not-found-reload/$id'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  ErrorComponentHydrationRoute: typeof ErrorComponentHydrationRoute
   UseQueryRoute: typeof UseQueryRoute
   LoaderFetchQueryTypeRoute: typeof LoaderFetchQueryTypeRoute
   NotFoundReloadIdRoute: typeof NotFoundReloadIdRoute
@@ -87,6 +104,13 @@ declare module '@tanstack/solid-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/error-component-hydration': {
+      id: '/error-component-hydration'
+      path: '/error-component-hydration'
+      fullPath: '/error-component-hydration'
+      preLoaderRoute: typeof ErrorComponentHydrationRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/useQuery': {
       id: '/useQuery'
       path: '/useQuery'
@@ -113,6 +137,7 @@ declare module '@tanstack/solid-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  ErrorComponentHydrationRoute: ErrorComponentHydrationRoute,
   UseQueryRoute: UseQueryRoute,
   LoaderFetchQueryTypeRoute: LoaderFetchQueryTypeRoute,
   NotFoundReloadIdRoute: NotFoundReloadIdRoute,

e2e/solid-start/query-integration/src/routes/error-component-hydration.tsx

@@ -0,0 +1,38 @@
+import { createFileRoute } from '@tanstack/solid-router'
+import { createSignal } from 'solid-js'
+import type { ErrorComponentProps } from '@tanstack/solid-router'
+
+export const Route = createFileRoute('/error-component-hydration')({
+  validateSearch: (search) => ({
+    falsy: search.falsy === true || search.falsy === 'true',
+  }),
+  loaderDeps: ({ search }) => ({ falsy: search.falsy }),
+  loader: ({ deps }) => {
+    const loaderError = deps.falsy ? undefined : new Error('loader failed')
+    throw loaderError
+  },
+  component: () => <p data-testid="route-content">Route content</p>,
+  errorComponent: InteractiveErrorComponent,
+})
+
+function InteractiveErrorComponent(props: ErrorComponentProps) {
+  const [clicked, setClicked] = createSignal(false)
+
+  return (
+    <section data-testid="error-component">
+      <p data-testid="error-message">
+        {props.error instanceof Error
+          ? props.error.message
+          : String(props.error)}
+      </p>
+      <button
+        type="button"
+        data-testid="error-component-button"
+        data-clicked={clicked() ? 'true' : 'false'}
+        onClick={() => setClicked(true)}
+      >
+        Error action
+      </button>
+    </section>
+  )
+}

e2e/solid-start/query-integration/tests/error-component-hydration.spec.ts

@@ -0,0 +1,55 @@
+import { expect } from '@playwright/test'
+import { test } from '@tanstack/router-e2e-utils'
+import type { Page } from '@playwright/test'
+
+test.use({
+  whitelistErrors: [/Failed to load resource.*500/],
+})
+
+async function expectHydratedErrorComponent(
+  page: Page,
+  path: string,
+  message: string,
+) {
+  const hydrationWarnings: Array<string> = []
+  page.on('console', (consoleMessage) => {
+    if (
+      consoleMessage.text().includes('Hydration key miss') ||
+      consoleMessage.text().includes('unclaimed server-rendered')
+    ) {
+      hydrationWarnings.push(consoleMessage.text())
+    }
+  })
+
+  const response = await page.goto(path)
+
+  expect(response?.status()).toBe(500)
+  await expect(page.getByTestId('route-content')).toHaveCount(0)
+  await expect(page.getByTestId('error-message')).toHaveText(message)
+
+  const button = page.getByTestId('error-component-button')
+  await expect(button).toHaveAttribute('data-clicked', 'false')
+  await button.click()
+  await expect(button).toHaveAttribute('data-clicked', 'true')
+  expect(hydrationWarnings).toEqual([])
+}
+
+test('SSR error component is claimed during hydration and remains interactive', async ({
+  page,
+}) => {
+  await expectHydratedErrorComponent(
+    page,
+    '/error-component-hydration',
+    'loader failed',
+  )
+})
+
+test('falsy loader errors still render an interactive hydrated error component', async ({
+  page,
+}) => {
+  await expectHydratedErrorComponent(
+    page,
+    '/error-component-hydration?falsy=true',
+    'undefined',
+  )
+})

packages/solid-router/src/CatchBoundary.tsx

@@ -4,15 +4,15 @@ import { renderInNonRouteComponentContext } from './nonRouteComponentContext'
 import type { ErrorRouteComponent } from './route'
 import type { JSX } from '@solidjs/web'
 
-export function CatchBoundary(
-  props: {
-    getResetKey: () => unknown
-    children?: JSX.Element
-    render?: () => JSX.Element
-    errorComponent?: ErrorRouteComponent
-    onCatch?: (error: Error) => void
-  } & Solid.ParentProps,
-) {
+type CatchBoundaryProps = {
+  getResetKey: () => unknown
+  children?: JSX.Element
+  render?: () => JSX.Element
+  errorComponent?: ErrorRouteComponent
+  onCatch?: (error: Error) => void
+} & Solid.ParentProps
+
+export function CatchBoundary(props: CatchBoundaryProps) {
   const [retryKey, setRetryKey] = Solid.createSignal<object>({})
   let resetBoundary: (() => void) | undefined
   let initialized = false
@@ -58,24 +58,7 @@ export function CatchBoundary(
         props.onCatch?.(resolvedError)
         resetBoundary = reset
 
-        return process.env.NODE_ENV !== 'production' ? (
-          renderInNonRouteComponentContext(
-            () => (
-              <Dynamic
-                component={props.errorComponent ?? ErrorComponent}
-                error={resolvedError}
-                reset={reset}
-              />
-            ),
-            'errorComponent',
-          )
-        ) : (
-          <Dynamic
-            component={props.errorComponent ?? ErrorComponent}
-            error={resolvedError}
-            reset={reset}
-          />
-        )
+        return renderErrorComponent(props, resolvedError, reset)
       }}
     >
       <Solid.Show when={retryKey()} keyed>
@@ -85,6 +68,90 @@ export function CatchBoundary(
   )
 }
 
+// Route load errors already exist in match state during SSR. Render them at
+// the boundary position on both the server and client so Solid hydrates the
+// same owner tree instead of entering its error fallback from only one side.
+export function RouteCatchBoundary(
+  props: CatchBoundaryProps & {
+    hasError: () => boolean
+    getError: () => unknown
+    isServer: boolean
+  },
+) {
+  const [retryKey, setRetryKey] = Solid.createSignal<object>({})
+  let initialized = false
+  let previousError: unknown
+
+  Solid.createEffect(props.getError, (error) => {
+    if (!initialized) {
+      initialized = true
+      previousError = error
+      return
+    }
+    if (Object.is(error, previousError)) {
+      return
+    }
+    previousError = error
+    setRetryKey({})
+  })
+
+  const renderRouteError = () => {
+    const resolvedError = Solid.untrack(props.getError) as Error
+    const reset = () => setRetryKey({})
+
+    if (!props.isServer) {
+      props.onCatch?.(resolvedError)
+    }
+
+    return renderErrorComponent(props, resolvedError, reset)
+  }
+
+  return (
+    <Solid.Show
+      when={props.hasError()}
+      fallback={
+        <CatchBoundary
+          getResetKey={props.getResetKey}
+          errorComponent={props.errorComponent}
+          onCatch={props.onCatch}
+          render={props.render}
+        >
+          {props.children}
+        </CatchBoundary>
+      }
+    >
+      <Solid.Show when={retryKey()} keyed>
+        {(_retryKey) => renderRouteError()}
+      </Solid.Show>
+    </Solid.Show>
+  )
+}
+
+function renderErrorComponent(
+  props: Pick<CatchBoundaryProps, 'errorComponent'>,
+  resolvedError: Error,
+  reset: () => void,
+) {
+  return process.env.NODE_ENV !== 'production' ? (
+    renderInNonRouteComponentContext(
+      () => (
+        <Dynamic
+          component={props.errorComponent ?? ErrorComponent}
+          error={resolvedError}
+          reset={reset}
+        />
+      ),
+      'errorComponent',
+    )
+  ) : (
+    <Dynamic
+      component={props.errorComponent ?? ErrorComponent}
+      error={resolvedError}
+      reset={reset}
+    />
+  )
+}
+
 export function ErrorComponent({ error }: { error: any }) {
   const [show, setShow] = Solid.createSignal(
     process.env.NODE_ENV !== 'production',