router-core-search-params

Validate and manage URL search params in TanStack Router with Zod, Valibot, or ArkType schemas.

Updated Dec 21, 2025
One-click install
npx skills add https://github.com/Angael/veles --skill router-core-search-params-angael
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: router-core-search-params
Source: https://github.com/Angael/veles/tree/main/.agents/skills/router-core-search-params
Command: npx skills add https://github.com/Angael/veles --skill router-core-search-params-angael

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires zod, @tanstack/zod-adapter, valibot, arktype, and includes references (resource) components.

What problem does it solve? URL search params in TanStack Router applications need type-safe validation, correct serialization, and predictable inheritance across routes. Without proper patterns, developers lose type safety, break loader caching, or silently drop params during navigation. ## Core Features & Use Cases - Schema-Based Validation: Define validateSearch with Zod (via @tanstack/zod-adapter), Valibot, or ArkType so search params are parsed into fully typed objects with defaults and fallbacks. - Reading and Writing Params: Use Route.useSearch(), getRouteApi(), useSearch({ strict: false }), Link with function-form search, and useNavigate() to read and update params without losing existing state. - Search Middlewares and Serialization: Apply retainSearchParams and stripSearchParams middlewares, customize parseSearch/stringifySearch, and scope loaderDeps so loaders only re-run when relevant params change. - Use Case: Build a paginated product list where page, filter, and sort live in the URL, survive navigation, inherit from a parent route, and trigger data refetches only when the page changes. ## Quick Start Add a Zod search schema with validateSearch to my TanStack Router products route and show me how to read and update the page param.

Frequently Asked Questions about router-core-search-params

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I validate search params in TanStack Router?

Define a schema with Zod, Valibot, or ArkType and pass it to the route's validateSearch option. TanStack Router parses the URL into structured JSON and validates it, giving you fully typed params via Route.useSearch().

How do I update search params without losing existing ones in TanStack Router?

Use the function form of the search option on Link or useNavigate: search={(prev) => ({ ...prev, page: prev.page + 1 })}. Passing a plain object replaces all params, while the function form merges your changes into the current state.

Should I use Zod, Valibot, or ArkType for TanStack Router search validation?

All three work. Valibot and ArkType implement Standard Schema and pass directly to validateSearch, while Zod v3 needs the @tanstack/zod-adapter with fallback() instead of .catch() to preserve inferred types. Zod v4 uses .catch() directly.

Why does zodValidator make my search param type unknown?

Using Zod v3's .catch() with zodValidator() widens the output type to unknown, destroying type safety. Use fallback() from @tanstack/zod-adapter instead, which preserves the inferred type while providing a default on parse failure.

Why does my TanStack Router loader re-run on every search param change?

Returning the entire search object from loaderDeps makes the loader re-run when any param changes. Pick only the params the loader needs, such as loaderDeps: ({ search }) => ({ page: search.page }), so refetches are scoped to relevant changes.

Can I put Date objects in TanStack Router search params?

No. Date objects do not serialize correctly to JSON in URLs. Convert dates to ISO strings with toISOString() before navigating, and parse them back with new Date() inside your component when needed.