@benjavicente/router-core 1.168.9

package/skills/router-core/search-params/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: router-core/search-params
+description: >-
+  validateSearch, search param validation with Zod/Valibot/ArkType adapters,
+  fallback(), search middlewares (retainSearchParams, stripSearchParams),
+  custom serialization (parseSearch, stringifySearch), search param
+  inheritance, loaderDeps for cache keys, reading and writing search params.
+type: sub-skill
+library: tanstack-router
+library_version: '1.166.2'
+requires:
+  - router-core
+sources:
+  - TanStack/router:docs/router/guide/search-params.md
+  - TanStack/router:docs/router/how-to/setup-basic-search-params.md
+  - TanStack/router:docs/router/how-to/validate-search-params.md
+  - TanStack/router:docs/router/how-to/navigate-with-search-params.md
+  - TanStack/router:docs/router/how-to/share-search-params-across-routes.md
+  - TanStack/router:docs/router/guide/custom-search-param-serialization.md
+---
+
+# Search Params
+
+TanStack Router treats search params as JSON-first application state. They are automatically parsed from the URL into structured objects (numbers, booleans, arrays, nested objects) and validated via `validateSearch` on each route.
+
+> **CRITICAL**: When using `zodValidator()` and Zod v3, use `fallback()` from `@benjavicente/zod-adapter`, NOT zod's `.catch()`. Using `.catch()` with the zod adapter makes the output type `unknown`, destroying type safety. This does not apply to Valibot or ArkType (which use their own fallback mechanisms). It also does not apply to Zod v4, which should use `.catch()` and not use the `zodValidator()`.
+> **CRITICAL**: Types are fully inferred. Never annotate the return of `useSearch()`.
+
+## Setup: Zod Adapter (Recommended)
+
+```bash
+npm install zod @benjavicente/zod-adapter
+```
+
+```tsx
+// src/routes/products.tsx
+import { createFileRoute } from '@benjavicente/react-router'
+import { z } from 'zod'
+
+const productSearchSchema = z.object({
+  page: z.number().default(1).catch(1),
+  filter: z.string().default(''),
+  sort: z.enum(['newest', 'oldest', 'price']).default('newest').catch('newest'),
+})
+
+export const Route = createFileRoute('/products')({
+  validateSearch: productSearchSchema,
+  component: ProductsPage,
+})
+
+function ProductsPage() {
+  // page: number, filter: string, sort: 'newest' | 'oldest' | 'price'
+  // ALL INFERRED — do not annotate
+  const { page, filter, sort } = Route.useSearch()
+
+  return (
+    <div>
+      <p>
+        Page {page}, filter: {filter}, sort: {sort}
+      </p>
+    </div>
+  )
+}
+```
+
+## Reading Search Params
+
+### In Route Components: `Route.useSearch()`
+
+```tsx
+function ProductsPage() {
+  const { page, sort } = Route.useSearch()
+  return <div>Page {page}</div>
+}
+```
+
+### In Code-Split Components: `getRouteApi()`
+
+```tsx
+import { getRouteApi } from '@benjavicente/react-router'
+
+const routeApi = getRouteApi('/products')
+
+function ProductFilters() {
+  const { sort } = routeApi.useSearch()
+  return <select value={sort}>{/* options */}</select>
+}
+```
+
+### From Any Component: `useSearch({ from })`
+
+```tsx
+import { useSearch } from '@benjavicente/react-router'
+
+function SortIndicator() {
+  const { sort } = useSearch({ from: '/products' })
+  return <span>Sorted by: {sort}</span>
+}
+```
+
+### Loose Access: `useSearch({ strict: false })`
+
+```tsx
+function GenericPaginator() {
+  const search = useSearch({ strict: false })
+  // search.page is number | undefined (union of all routes)
+  return <span>Page: {search.page ?? 1}</span>
+}
+```
+
+## Writing Search Params
+
+### Link with Function Form (Preserves Existing Params)
+
+```tsx
+import { Link } from '@benjavicente/react-router'
+
+function Pagination() {
+  return (
+    <Link
+      from="/products"
+      search={(prev) => ({ ...prev, page: prev.page + 1 })}
+    >
+      Next Page
+    </Link>
+  )
+}
+```
+
+### Link with Object Form (Replaces All Params)
+
+```tsx
+<Link to="/products" search={{ page: 1, filter: '', sort: 'newest' }}>
+  Reset
+</Link>
+```
+
+### Programmatic: `useNavigate()`
+
+```tsx
+import { useNavigate } from '@benjavicente/react-router'
+
+function SortDropdown() {
+  const navigate = useNavigate({ from: '/products' })
+
+  return (
+    <select
+      onChange={(e) => {
+        navigate({
+          search: (prev) => ({ ...prev, sort: e.target.value, page: 1 }),
+        })
+      }}
+    >
+      <option value="newest">Newest</option>
+      <option value="price">Price</option>
+    </select>
+  )
+}
+```
+
+## Search Param Inheritance
+
+Parent route search params are automatically merged into child routes:
+
+```tsx
+// src/routes/shop.tsx — parent defines shared params
+import { createFileRoute } from '@benjavicente/react-router'
+import { z } from 'zod'
+
+const shopSearchSchema = z.object({
+  currency: z.enum(['USD', 'EUR']).default('USD').catch('USD'),
+})
+
+export const Route = createFileRoute('/shop')({
+  validateSearch: shopSearchSchema,
+})
+```
+
+```tsx
+// src/routes/shop/products.tsx — child inherits currency
+import { createFileRoute } from '@benjavicente/react-router'
+
+export const Route = createFileRoute('/shop/products')({
+  component: ShopProducts,
+})
+
+function ShopProducts() {
+  // currency is available here from parent — fully typed
+  const { currency } = Route.useSearch()
+  return <div>Currency: {currency}</div>
+}
+```
+
+## Search Middlewares
+
+### `retainSearchParams` — Keep Params Across Navigation
+
+```tsx
+import { createRootRoute, retainSearchParams } from '@benjavicente/react-router'
+import { z } from 'zod'
+
+const rootSearchSchema = z.object({
+  debug: z.boolean().optional(),
+})
+
+export const Route = createRootRoute({
+  validateSearch: rootSearchSchema,
+  search: {
+    middlewares: [retainSearchParams(['debug'])],
+  },
+})
+```
+
+### `stripSearchParams` — Remove Default Values from URL
+
+```tsx
+import { createFileRoute, stripSearchParams } from '@benjavicente/react-router'
+import { z } from 'zod'
+
+const defaults = { sort: 'newest', page: 1 }
+
+const searchSchema = z.object({
+  sort: z.string().default(defaults.sort),
+  page: z.number().default(defaults.page),
+})
+
+export const Route = createFileRoute('/items')({
+  validateSearch: searchSchema,
+  search: {
+    middlewares: [stripSearchParams(defaults)],
+  },
+})
+```
+
+### Chaining Middlewares
+
+```tsx
+export const Route = createFileRoute('/search')({
+  validateSearch: z.object({
+    retainMe: z.string().optional(),
+    arrayWithDefaults: z.string().array().default(['foo', 'bar']),
+    required: z.string(),
+  }),
+  search: {
+    middlewares: [
+      retainSearchParams(['retainMe']),
+      stripSearchParams({ arrayWithDefaults: ['foo', 'bar'] }),
+    ],
+  },
+})
+```
+
+## Custom Serialization
+
+Override the default JSON serialization at the router level:
+
+```tsx
+import {
+  createRouter,
+  parseSearchWith,
+  stringifySearchWith,
+} from '@benjavicente/react-router'
+
+const router = createRouter({
+  routeTree,
+  // Example: use JSURL2 for compact, human-readable URLs
+  parseSearch: parseSearchWith(parse),
+  stringifySearch: stringifySearchWith(stringify),
+})
+```
+
+## Using Search Params in Loaders via `loaderDeps`
+
+```tsx
+export const Route = createFileRoute('/products')({
+  validateSearch: productSearchSchema,
+  // Pick ONLY the params the loader needs — not the entire search object
+  loaderDeps: ({ search }) => ({ page: search.page }),
+  loader: async ({ deps }) => {
+    return fetchProducts({ page: deps.page })
+  },
+})
+```
+
+## Common Mistakes
+
+### 1. HIGH: Using zod v3's `.catch()` with `zodValidator()` instead of adapter `fallback()`
+
+```tsx
+// WRONG — .catch() with zodValidator makes the type unknown
+const schema = z.object({ page: z.number().catch(1) })
+validateSearch: zodValidator(schema) // page is typed as unknown!
+
+// CORRECT — fallback() preserves the inferred type
+import { fallback } from '@benjavicente/zod-adapter'
+const schema = z.object({ page: fallback(z.number(), 1) })
+```
+
+**Important:** This only applies when using Zod v3, not when using Zod v4. For v4, using `.catch()` is correct.
+
+### 2. HIGH: Returning entire search object from `loaderDeps`
+
+```tsx
+// WRONG — loader re-runs on ANY search param change
+loaderDeps: ({ search }) => search
+
+// CORRECT — loader only re-runs when page changes
+loaderDeps: ({ search }) => ({ page: search.page })
+```
+
+### 3. HIGH: Passing Date objects in search params
+
+```tsx
+// WRONG — Date does not serialize correctly to JSON in URLs
+<Link search={{ startDate: new Date() }}>
+
+// CORRECT — convert to ISO string
+<Link search={{ startDate: new Date().toISOString() }}>
+```
+
+### 4. MEDIUM: Parent route missing `validateSearch` blocks inheritance
+
+```tsx
+// WRONG — child cannot access shared params
+export const Route = createRootRoute({
+  component: RootComponent,
+  // no validateSearch!
+})
+
+// CORRECT — parent must define validateSearch for children to inherit
+export const Route = createRootRoute({
+  validateSearch: globalSearchSchema,
+  component: RootComponent,
+})
+```
+
+### 5. HIGH (cross-skill): Using search as object instead of function loses params
+
+```tsx
+// WRONG — replaces ALL search params, losing any existing ones
+<Link to="." search={{ page: 2 }}>Page 2</Link>
+
+// CORRECT — preserves existing params, updates only page
+<Link to="." search={(prev) => ({ ...prev, page: 2 })}>Page 2</Link>
+```
+
+## References
+
+- [Validation Patterns Reference](./references/validation-patterns.md) — comprehensive patterns for all validation libraries

package/skills/router-core/search-params/references/validation-patterns.md

@@ -0,0 +1,379 @@
+# Search Param Validation Patterns Reference
+
+Comprehensive validation patterns for TanStack Router search params across all supported validation approaches.
+
+## Zod with `@benjavicente/zod-adapter`
+
+Zod v3 does not implement Standard Schema, so the `@benjavicente/zod-adapter` wrapper is required. Always use `fallback()` from the adapter instead of zod's `.catch()`. Always wrap with `zodValidator()`.
+
+### Basic Types
+
+```tsx
+import { zodValidator, fallback } from '@benjavicente/zod-adapter'
+import { z } from 'zod'
+
+const schema = z.object({
+  count: fallback(z.number(), 0),
+  name: fallback(z.string(), ''),
+  active: fallback(z.boolean(), true),
+})
+
+export const Route = createFileRoute('/example')({
+  validateSearch: zodValidator(schema),
+})
+```
+
+### Optional Params
+
+```tsx
+const schema = z.object({
+  // Truly optional — can be undefined in component
+  searchTerm: z.string().optional(),
+  // Optional in URL but always has a value in component
+  page: fallback(z.number(), 1).default(1),
+})
+```
+
+### Default Values
+
+```tsx
+const schema = z.object({
+  // .default() means the param is optional during navigation
+  // but always present (with default) when reading
+  page: fallback(z.number(), 1).default(1),
+  sort: fallback(z.enum(['name', 'date', 'price']), 'name').default('name'),
+  ascending: fallback(z.boolean(), true).default(true),
+})
+```
+
+### Array Params
+
+```tsx
+const schema = z.object({
+  tags: fallback(z.string().array(), []).default([]),
+  selectedIds: fallback(z.number().array(), []).default([]),
+})
+
+// URL: /items?tags=%5B%22react%22%2C%22typescript%22%5D&selectedIds=%5B1%2C2%2C3%5D
+// Parsed: { tags: ['react', 'typescript'], selectedIds: [1, 2, 3] }
+```
+
+### Nested Object Params
+
+```tsx
+const schema = z.object({
+  filters: fallback(
+    z.object({
+      status: z.enum(['active', 'inactive']).optional(),
+      tags: z.string().array().optional(),
+      priceRange: z
+        .object({
+          min: z.number().min(0),
+          max: z.number().min(0),
+        })
+        .optional(),
+    }),
+    {},
+  ).default({}),
+})
+```
+
+### Enum with Constraints
+
+```tsx
+const schema = z.object({
+  sort: fallback(z.enum(['newest', 'oldest', 'price']), 'newest').default(
+    'newest',
+  ),
+  page: fallback(z.number().int().min(1).max(1000), 1).default(1),
+  limit: fallback(z.number().int().min(10).max(100), 20).default(20),
+})
+```
+
+### Discriminated Union
+
+```tsx
+const schema = z.object({
+  searchType: fallback(z.enum(['basic', 'advanced']), 'basic').default('basic'),
+  query: fallback(z.string(), '').default(''),
+  // Advanced-only fields are optional
+  category: z.string().optional(),
+  minPrice: z.number().optional(),
+  maxPrice: z.number().optional(),
+})
+```
+
+For true discriminated union validation:
+
+```tsx
+const basicSearch = z.object({
+  searchType: z.literal('basic'),
+  query: z.string(),
+})
+
+const advancedSearch = z.object({
+  searchType: z.literal('advanced'),
+  query: z.string(),
+  category: z.string(),
+  minPrice: z.number(),
+  maxPrice: z.number(),
+})
+
+const schema = z.discriminatedUnion('searchType', [basicSearch, advancedSearch])
+
+export const Route = createFileRoute('/search')({
+  validateSearch: zodValidator(schema),
+})
+```
+
+### Input Transforms (String to Number)
+
+When using the zod adapter with transforms, configure `input` and `output` types:
+
+```tsx
+const schema = z.object({
+  page: fallback(z.number(), 1).default(1),
+  filter: fallback(z.string(), '').default(''),
+})
+
+export const Route = createFileRoute('/items')({
+  // Default: input type used for navigation, output type used for reading
+  validateSearch: zodValidator(schema),
+
+  // Advanced: swap input/output inference
+  // validateSearch: zodValidator({ schema, input: 'output', output: 'input' }),
+})
+```
+
+### Schema Composition
+
+```tsx
+const paginationSchema = z.object({
+  page: fallback(z.number().int().positive(), 1).default(1),
+  limit: fallback(z.number().int().min(1).max(100), 20).default(20),
+})
+
+const sortSchema = z.object({
+  sortBy: z.enum(['name', 'date', 'relevance']).optional(),
+  sortOrder: z.enum(['asc', 'desc']).optional(),
+})
+
+// Compose for specific routes
+const productSearchSchema = paginationSchema.extend({
+  category: z.string().optional(),
+  inStock: fallback(z.boolean(), true).default(true),
+})
+
+const userSearchSchema = paginationSchema.merge(sortSchema).extend({
+  role: z.enum(['admin', 'user']).optional(),
+})
+```
+
+---
+
+## Valibot (Standard Schema)
+
+Valibot 1.0+ implements Standard Schema. No adapter wrapper needed — pass the schema directly to `validateSearch`. The `@benjavicente/valibot-adapter` is optional and only needed for explicit input/output type control.
+
+```bash
+npm install valibot
+```
+
+```tsx
+import { createFileRoute } from '@benjavicente/react-router'
+import * as v from 'valibot'
+
+const productSearchSchema = v.object({
+  page: v.optional(v.fallback(v.number(), 1), 1),
+  filter: v.optional(v.fallback(v.string(), ''), ''),
+  sort: v.optional(
+    v.fallback(v.picklist(['newest', 'oldest', 'price']), 'newest'),
+    'newest',
+  ),
+})
+
+export const Route = createFileRoute('/products')({
+  // Pass schema directly — Standard Schema compliant
+  validateSearch: productSearchSchema,
+  component: ProductsPage,
+})
+
+function ProductsPage() {
+  const { page, filter, sort } = Route.useSearch()
+  return <div>Page {page}</div>
+}
+```
+
+### Valibot with Constraints
+
+```tsx
+import * as v from 'valibot'
+
+const schema = v.object({
+  page: v.optional(
+    v.fallback(v.pipe(v.number(), v.integer(), v.minValue(1)), 1),
+    1,
+  ),
+  query: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(100))),
+  tags: v.optional(v.fallback(v.array(v.string()), []), []),
+})
+```
+
+### Valibot with Adapter (Alternative)
+
+If you need explicit input/output type control:
+
+```tsx
+import { valibotValidator } from '@benjavicente/valibot-adapter'
+import * as v from 'valibot'
+
+const schema = v.object({
+  page: v.optional(v.fallback(v.number(), 1), 1),
+})
+
+export const Route = createFileRoute('/items')({
+  validateSearch: valibotValidator(schema),
+})
+```
+
+---
+
+## ArkType (Standard Schema)
+
+ArkType 2.0-rc+ implements Standard Schema. No adapter needed — pass the type directly to `validateSearch`. The `@benjavicente/arktype-adapter` is optional and only needed for explicit input/output type control.
+
+```bash
+npm install arktype
+```
+
+```tsx
+import { createFileRoute } from '@benjavicente/react-router'
+import { type } from 'arktype'
+
+const productSearchSchema = type({
+  page: 'number = 1',
+  filter: 'string = ""',
+  sort: '"newest" | "oldest" | "price" = "newest"',
+})
+
+export const Route = createFileRoute('/products')({
+  // Pass directly — Standard Schema compliant
+  validateSearch: productSearchSchema,
+  component: ProductsPage,
+})
+
+function ProductsPage() {
+  const { page, filter, sort } = Route.useSearch()
+  return <div>Page {page}</div>
+}
+```
+
+### ArkType with Constraints
+
+```tsx
+import { type } from 'arktype'
+
+const searchSchema = type({
+  'query?': 'string>0&<=100',
+  page: 'number>0 = 1',
+  'sortBy?': "'name'|'date'|'relevance'",
+  'filters?': 'string[]',
+})
+```
+
+---
+
+## Manual Validation Function
+
+For full control without any library. The function receives raw JSON-parsed (but unvalidated) search params.
+
+```tsx
+import { createFileRoute } from '@benjavicente/react-router'
+
+type ProductSearch = {
+  page: number
+  filter: string
+  sort: 'newest' | 'oldest' | 'price'
+}
+
+export const Route = createFileRoute('/products')({
+  validateSearch: (search: Record<string, unknown>): ProductSearch => ({
+    page: Number(search?.page ?? 1),
+    filter: (search.filter as string) || '',
+    sort:
+      search.sort === 'newest' ||
+      search.sort === 'oldest' ||
+      search.sort === 'price'
+        ? search.sort
+        : 'newest',
+  }),
+  component: ProductsPage,
+})
+
+function ProductsPage() {
+  const { page, filter, sort } = Route.useSearch()
+  return <div>Page {page}</div>
+}
+```
+
+### Manual Validation with Error Throwing
+
+If `validateSearch` throws, the route's `errorComponent` renders instead:
+
+```tsx
+export const Route = createFileRoute('/products')({
+  validateSearch: (search: Record<string, unknown>) => {
+    const page = Number(search.page)
+    if (isNaN(page) || page < 1) {
+      throw new Error('Invalid page number')
+    }
+    return { page }
+  },
+  errorComponent: ({ error }) => <div>Bad search params: {error.message}</div>,
+})
+```
+
+---
+
+## Pattern: Object with `parse` Method
+
+Any object with a `.parse()` method works as `validateSearch`:
+
+```tsx
+const mySchema = {
+  parse: (input: Record<string, unknown>) => ({
+    page: Number(input.page ?? 1),
+    query: String(input.query ?? ''),
+  }),
+}
+
+export const Route = createFileRoute('/search')({
+  validateSearch: mySchema,
+})
+```
+
+---
+
+## Dates in Search Params
+
+Never put `Date` objects in search params. Always use ISO strings:
+
+```tsx
+const schema = z.object({
+  // Store as string, parse in component if needed
+  startDate: z.string().optional(),
+  endDate: z.string().optional(),
+})
+
+// In component:
+function DateFilter() {
+  const { startDate } = Route.useSearch()
+  const date = startDate ? new Date(startDate) : null
+  return <div>{date?.toLocaleDateString()}</div>
+}
+
+// When navigating:
+;<Link search={(prev) => ({ ...prev, startDate: new Date().toISOString() })}>
+  Set Start Date
+</Link>
+```