feat: add support for zod v4 (#4322)

Author: niba

packages/zod-adapter/package.json

@@ -67,7 +67,7 @@
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.2.0",
     "@tanstack/react-router": "workspace:^",
-    "zod": "^3.24.2",
+    "zod": "^3.25.64",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

packages/zod-adapter/src/index.ts

@@ -1,4 +1,5 @@
-import { z } from 'zod'
+import * as z3 from 'zod'
+import * as z4 from 'zod/v4'
 import type { ValidatorAdapter } from '@tanstack/react-router'
 
 export interface ZodTypeLike {
@@ -58,12 +59,32 @@ export const zodValidator = <
   }
 }
 
-export const fallback = <TSchema extends z.ZodTypeAny>(
+const isZod3Schema = (schema: any): schema is z3.ZodSchema => {
+  return (
+    '_def' in schema &&
+    typeof schema._def === 'object' &&
+    'typeName' in schema._def
+  )
+}
+
+export function fallback<TSchema extends z3.ZodTypeAny>(
   schema: TSchema,
   fallback: TSchema['_input'],
-): z.ZodPipeline<
-  z.ZodType<TSchema['_input'], z.ZodTypeDef, TSchema['_input']>,
-  z.ZodCatch<TSchema>
-> => {
-  return z.custom<TSchema['_input']>().pipe(schema.catch(fallback))
+): z3.ZodPipeline<
+  z3.ZodType<TSchema['_input'], z3.ZodTypeDef, TSchema['_input']>,
+  z3.ZodCatch<TSchema>
+>
+export function fallback<TSchema extends z4.ZodTypeAny>(
+  schema: TSchema,
+  fallback: z4.output<TSchema>,
+): z4.ZodPipe<
+  z4.ZodType<TSchema['_input'], TSchema['_input']>,
+  z4.ZodCatch<TSchema>
+>
+export function fallback(schema: any, fallback: any): any {
+  if (isZod3Schema(schema)) {
+    return z3.custom().pipe(schema.catch(fallback))
+  } else {
+    return z4.custom().pipe(schema.catch(fallback))
+  }
 }

packages/zod-adapter/tests/index.test-d.ts renamed to packages/zod-adapter/tests/zod-v3.test-d.ts

@@ -5,7 +5,7 @@ import {
   Link,
 } from '@tanstack/react-router'
 import { test, expectTypeOf } from 'vitest'
-import { zodValidator } from '../src'
+import { fallback, zodValidator } from '../src'
 import { z } from 'zod'
 
 test('when creating a route with zod validation', () => {
@@ -56,6 +56,42 @@ test('when creating a route with zod validation', () => {
   }>
 })
 
+test('when creating a route with zod validation and fallback handler', () => {
+  const rootRoute = createRootRoute({
+    validateSearch: zodValidator(
+      z.object({
+        page: z.number().optional().default(0),
+        sort: fallback(z.enum(['oldest', 'newest']), 'oldest').default(
+          'oldest',
+        ),
+      }),
+    ),
+  })
+
+  const router = createRouter({ routeTree: rootRoute })
+
+  expectTypeOf(Link<typeof router, string, '/'>)
+    .parameter(0)
+    .toHaveProperty('search')
+    .exclude<Function | true>()
+    .toEqualTypeOf<{ page?: number; sort?: 'oldest' | 'newest' } | undefined>()
+
+  expectTypeOf(Link<typeof router, string, '/'>)
+    .parameter(0)
+    .toHaveProperty('search')
+    .returns.toEqualTypeOf<{ page?: number; sort?: 'oldest' | 'newest' }>()
+
+  expectTypeOf(rootRoute.useSearch<typeof router>()).toEqualTypeOf<{
+    page: number
+    sort: 'oldest' | 'newest'
+  }>()
+
+  expectTypeOf(rootRoute.useSearch<typeof router>()).toEqualTypeOf<{
+    page: number
+    sort: 'oldest' | 'newest'
+  }>
+})
+
 test('when creating a route with zod validation where input is output', () => {
   const rootRoute = createRootRoute({
     validateSearch: zodValidator(

packages/zod-adapter/tests/index.test.tsx renamed to packages/zod-adapter/tests/zod-v3.test.tsx

@@ -1,5 +1,5 @@
 import { afterEach, expect, test, vi } from 'vitest'
-import { zodValidator } from '../src'
+import { fallback, zodValidator } from '../src'
 import { z } from 'zod'
 import {
   createRootRoute,
@@ -78,6 +78,70 @@ test('when navigating to a route with zodValidator', async () => {
   expect(await screen.findByText('Page: 0')).toBeInTheDocument()
 })
 
+test('when navigating to a route with zodValidator with fallback value', async () => {
+  const rootRoute = createRootRoute()
+
+  const Index = () => {
+    return (
+      <>
+        <h1>Index</h1>
+        <Link<typeof router, string, '/invoices'>
+          to="/invoices"
+          search={{
+            // to test fallback we need to cast to any to test invalid input
+            sort: 0 as any,
+          }}
+        >
+          To Invoices
+        </Link>
+      </>
+    )
+  }
+
+  const indexRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/',
+    component: Index,
+  })
+
+  const Invoices = () => {
+    const search = invoicesRoute.useSearch()
+
+    return (
+      <>
+        <h1>Invoices</h1>
+        <span>Sort by: {search.sort}</span>
+      </>
+    )
+  }
+
+  const invoicesRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: 'invoices',
+    validateSearch: zodValidator(
+      z.object({
+        sort: fallback(z.enum(['oldest', 'newest']), 'oldest').default(
+          'oldest',
+        ),
+      }),
+    ),
+    component: Invoices,
+  })
+
+  const routeTree = rootRoute.addChildren([indexRoute, invoicesRoute])
+  const router = createRouter({ routeTree })
+
+  render(<RouterProvider router={router} />)
+
+  const invoicesLink = await screen.findByRole('link', {
+    name: 'To Invoices',
+  })
+
+  fireEvent.click(invoicesLink)
+
+  expect(await screen.findByText('Sort by: oldest')).toBeInTheDocument()
+})
+
 test('when navigating to a route with zodValidator input set to output', async () => {
   const rootRoute = createRootRoute()