type-safety — скилл для Claude Code: типизация маршрутов TanStack Router
Скилл type-safety учит ИИ-кодеру правильно писать типизированный код с TanStack Router: не добавлять аннотации к выведенным значениям, использовать Register, сужать типы через from и getRouteApi.
MIT 223 установок ★ 15 341 обновлён 2026-10-25
npx skills add TanStack/router --skill type-safety -a claude-codeЧто делает type-safety
TanStack Router полностью выводит типы: параметры маршрута, поисковые параметры, контекст и данные загрузчика автоматически распространяются по дереву маршрутов. Главная ошибка ИИ-агентов — добавлять as Type, явные параметры генериков или аннотации к значениям, которые уже выведены. Это нарушает цепь типизации и скрывает настоящие ошибки.
Скилл охватывает единственную обязательную аннотацию — регистрацию модуля Register в файле роутера, без которой экспортированные хуки потеряют типы. Объясняет, как сужать типы через параметр from в хуках и Link, чтобы TypeScript проверял быстрее и точнее. Для компонентов, используемых в разных маршрутах, показывает strict: false, а для code-split файлов — getRouteApi вместо импорта конфигурации.
Содержит рекомендации по производительности TypeScript: объектный синтаксис для addChildren в больших деревьях маршрутов работает быстрее, чем кортежи. Скилл решает проблему, когда ИИ генерирует лишние типизации или путает TanStack Router с Next.js и React Router.
Какие задачи решает
- Убрать ненужные type-касты и аннотации в коде с TanStack Router
- Настроить регистрацию типов для верхнеуровневых экспортов маршрутизатора
- Сузить типы параметров маршрута в общих компонентах без замедления TypeScript
- Оптимизировать производительность типизации в крупном дереве маршрутов
- Научить ИИ отличать TanStack Router от Next.js и React Router
Примеры запросов агенту
- Добавь типизацию в файл роутера с
Registerмодулем для Claude Code - Сузь типы в компоненте
/posts/$postIdчерезfromвuseSearchиuseParams - Замени кортежный синтаксис на объектный в
addChildrenдля ускорения проверки типов
Как установить type-safety
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill type-safety -a claude-code2Вручную: положить файлы
~/.claude/skills/type-safety/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/type-safety/
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill type-safety -a codex2Вручную: положить файлы
.agents/skills/type-safety/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill type-safety -a cursor2Вручную: положить файлы
.cursor/skills/type-safety/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install TanStack/router packages/router-core/skills/router-core/type-safety2Вручную: положить файлы
.github/skills/type-safety/SKILL.md1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill type-safety -a gemini-cli2Командой платформы
gemini skills install https://github.com/TanStack/router --path packages/router-core/skills/router-core/type-safetyВручную: положить файлы
.devin/skills/type-safety/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add TanStack/router --skill type-safety -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о type-safety
Как установить type-safety для Claude Code?
Выполни npx skills add TanStack/router --skill type-safety -a claude-code, затем скилл загружается в ~/.claude/skills/type-safety/SKILL.md и будет применяться ко всем проектам с TanStack Router.
Что делает type-safety?
Скилл учит ИИ-кодера писать полностью типизированный код TanStack Router без ненужных аннотаций, использовать Register для регистрации типов, сужать типы через from и getRouteApi, а также оптимизировать производительность TypeScript в крупных маршрутизаторах.
Когда использовать from, а когда strict: false?
Используй from в компонентах, привязанных к конкретному маршруту, чтобы сузить типы и ускорить проверку. Используй strict: false в компонентах, которые используются в разных маршрутах и не нуждаются в точной типизации конкретного маршрута.
Исходный текст
SKILL.md · MIT
---
name: type-safety
description: >-
Full type inference philosophy (never cast, never annotate inferred
values), Register module declaration, from narrowing on hooks and
Link, strict:false for shared components, getRouteApi for code-split
typed access, addChildren with object syntax for TS perf, LinkProps
and ValidateLinkOptions type utilities, as const satisfies pattern.
metadata:
type: sub-skill
library: tanstack-router
library_version: '1.171.15'
requires:
- router-core
sources:
- TanStack/router:docs/router/guide/type-safety.md
- TanStack/router:docs/router/guide/type-utilities.md
- TanStack/router:docs/router/guide/render-optimizations.md
---
# Type Safety
TanStack Router is FULLY type-inferred. Params, search params, context, and loader data all flow through the route tree automatically. The **#1 AI agent mistake** is adding type annotations, casts, or generic parameters to values that are already inferred.
> **CRITICAL**: NEVER use `as Type`, explicit generic params, `satisfies` on hook returns, or type annotations on inferred values. Every cast masks real type errors and breaks the inference chain.
> **CRITICAL**: Do NOT confuse TanStack Router with Next.js or React Router. There is no `getServerSideProps`, no `useSearchParams()`, no `useLoaderData()` from `react-router-dom`.
## The ONE Required Type Annotation: Register
Without this, top-level exports like `Link`, `useNavigate`, `useSearch` have no type safety.
```tsx
// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
const router = createRouter({ routeTree })
// THIS IS REQUIRED — the single type registration for the entire app
declare module '@tanstack/react-router' {
interface Register {
router: typeof router
}
}
export default router
```
After registration, every `Link`, `useNavigate`, `useSearch`, `useParams` across the app is fully typed.
## Types Flow Automatically
### Route Hooks — No Annotation Needed
```tsx
// src/routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({
validateSearch: (search: Record<string, unknown>) => ({
page: Number(search.page ?? 1),
}),
loader: async ({ params }) => {
// params.postId is already typed as string — do not annotate
const post = await fetchPost(params.postId)
return { post }
},
component: PostComponent,
})
function PostComponent() {
// ALL of these are fully inferred — do NOT add type annotations
const { postId } = Route.useParams()
// ^? string
const { page } = Route.useSearch()
// ^? number
const { post } = Route.useLoaderData()
// ^? { id: string; title: string; body: string }
return (
<div>
<h1>{post.title}</h1>
<p>Page {page}</p>
</div>
)
}
```
### Context Flows Through the Tree
```tsx
// src/routes/__root.tsx
import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
interface RouterContext {
auth: { userId: string; role: 'admin' | 'user' } | null
}
// Note: createRootRouteWithContext is a FACTORY — call it TWICE: ()()
export const Route = createRootRouteWithContext<RouterContext>()({
component: () => <Outlet />,
})
```
```tsx
// src/routes/dashboard.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'
export const Route = createFileRoute('/dashboard')({
beforeLoad: ({ context }) => {
// context.auth is already typed as { userId: string; role: 'admin' | 'user' } | null
// NO annotation needed
if (!context.auth) throw redirect({ to: '/login' })
return { user: context.auth }
},
loader: ({ context }) => {
// context.user is typed as { userId: string; role: 'admin' | 'user' }
// This was added by beforeLoad above — fully inferred
return fetchDashboard(context.user.userId)
},
component: DashboardComponent,
})
function DashboardComponent() {
const data = Route.useLoaderData()
const { user } = Route.useRouteContext()
return <h1>Welcome {user.userId}</h1>
}
```
## Narrowing with `from`
Without `from`, hooks return a union of ALL routes' types — slow for TypeScript and imprecise.
### On Hooks
```tsx
import { useSearch, useParams, useNavigate } from '@tanstack/react-router'
function PostSidebar() {
// WRONG — search is a union of ALL routes' search params
const search = useSearch()
// CORRECT — search is narrowed to /posts/$postId's search params
const search = useSearch({ from: '/posts/$postId' })
// ^? { page: number }
// CORRECT — params narrowed to this route
const { postId } = useParams({ from: '/posts/$postId' })
// CORRECT — navigate narrowed for relative paths
const navigate = useNavigate({ from: '/posts/$postId' })
}
```
### On `Link`
```tsx
import { Link } from '@tanstack/react-router'
// WRONG — search resolves to union of ALL routes' search params, slow TS check
<Link to=".." search={{ page: 0 }} />
// CORRECT — narrowed, fast TS check
<Link from="/posts/$postId" to=".." search={{ page: 0 }} />
// Also correct — Route.fullPath in route components
<Link from={Route.fullPath} to=".." search={{ page: 0 }} />
```
## Shared Components: `strict: false`
When a component is used across multiple routes, use `strict: false` instead of `from`:
```tsx
import { useSearch } from '@tanstack/react-router'
function GlobalSearch() {
// Returns union of all routes' search params — no runtime error if route doesn't match
const search = useSearch({ strict: false })
return <span>Query: {search.q ?? ''}</span>
}
```
## Code-Split Files: `getRouteApi`
Use `getRouteApi` instead of importing `Route` to avoid pulling route config into the lazy chunk:
```tsx
// src/routes/posts.lazy.tsx
import { createLazyFileRoute, getRouteApi } from '@tanstack/react-router'
const routeApi = getRouteApi('/posts')
export const Route = createLazyFileRoute('/posts')({
component: PostsComponent,
})
function PostsComponent() {
const data = routeApi.useLoaderData()
const { page } = routeApi.useSearch()
return <div>Page {page}</div>
}
```
## TypeScript Performance
### Use Object Syntax for `addChildren` in Large Route Trees
```tsx
// SLOWER — tuple syntax
const routeTree = rootRoute.addChildren([
postsRoute.addChildren([postRoute, postsIndexRoute]),
indexRoute,
])
// FASTER — object syntax (TS checks objects faster than large tuples)
const routeTree = rootRoute.addChildren({
postsRoute: postsRoute.addChildren({ postRoute, postsIndexRoute }),
indexRoute,
})
```
With file-based routing the route tree is generated, so this is handled for you.
### Avoid Returning Unused Inferred Types from Loaders
When using external caches like TanStack Query, don't let the router infer complex return types you never consume:
```tsx
// SLOWER — TS infers the full query return type into the route tree
export const Route = createFileRoute('/posts/$postId')({
loader: ({ context: { queryClient }, params: { postId } }) =>
queryClient.query({ ...postQueryOptions(postId), staleTime: 'static' }),
component: PostComponent,
})
// FASTER — async loader returns no query data, inference stays out of the route tree
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ context: { queryClient }, params: { postId: id } }) => {
await queryClient.query({ ...postQueryOptions(id), staleTime: 'static' })
},
component: PostComponent,
})
```
### `as const satisfies` for Link Option Objects
Never use `LinkProps` as a variable type — it's an enormous union:
```tsx
import type { LinkProps, RegisteredRouter } from '@tanstack/react-router'
// WRONG — LinkProps is a massive union, extremely slow TS check
const wrongProps: LinkProps = { to: '/posts' }
// CORRECT — infer a precise type, validate against LinkProps
const goodProps = { to: '/posts' } as const satisfies LinkProps
// EVEN BETTER — narrow LinkProps with generic params
const narrowedProps = {
to: '/posts',
} as const satisfies LinkProps<RegisteredRouter, string, '/posts'>
```
### Type-Safe Link Option Arrays
```tsx
import type { LinkProps } from '@tanstack/react-router'
export const navLinks = [
{ to: '/posts' },
{ to: '/posts/$postId', params: { postId: '1' } },
] as const satisfies ReadonlyArray<LinkProps>
// Use the precise inferred type, not LinkProps directly
export type NavLink = (typeof navLinks)[number]
```
## Type Utilities for Generic Components
### `ValidateLinkOptions` — Type-Safe Link Props in Custom Components
```tsx
import {
Link,
type RegisteredRouter,
type ValidateLinkOptions,
} from '@tanstack/react-router'
interface NavItemProps<
TRouter extends RegisteredRouter = RegisteredRouter,
TOptions = unknown,
> {
label: string
linkOptions: ValidateLinkOptions<TRouter, TOptions>
}
export function NavItem<TRouter extends RegisteredRouter, TOptions>(
props: NavItemProps<TRouter, TOptions>,
): React.ReactNode
export function NavItem(props: NavItemProps): React.ReactNode {
return (
<li>
<Link {...props.linkOptions}>{props.label}</Link>
</li>
)
}
// Usage — fully type-safe
<NavItem label="Posts" linkOptions={{ to: '/posts' }} />
<NavItem label="Post" linkOptions={{ to: '/posts/$postId', params: { postId: '1' } }} />
```
### `ValidateNavigateOptions` and `ValidateRedirectOptions`
Same pattern as `ValidateLinkOptions` above, for `useNavigate` and `redirect`. Declare a generic public overload plus a non-generic implementation signature so the call site stays narrowed and the body works without casts:
```tsx
import {
useNavigate,
type RegisteredRouter,
type ValidateNavigateOptions,
} from '@tanstack/react-router'
export function useDelayedNavigate<
TRouter extends RegisteredRouter = RegisteredRouter,
TOptions = unknown,
>(
options: ValidateNavigateOptions<TRouter, TOptions>,
delayMs: number,
): () => void
export function useDelayedNavigate(
options: ValidateNavigateOptions,
delayMs: number,
) {
const navigate = useNavigate()
return () => {
setTimeout(() => navigate(options), delayMs)
}
}
```
`ValidateRedirectOptions` works identically — declare a generic overload accepting `ValidateRedirectOptions<TRouter, TOptions>` and an impl signature accepting `ValidateRedirectOptions`, then call `redirect(options)` in the body.
### Render Props for Maximum Performance
Instead of accepting `LinkProps`, invert control so `Link` is narrowed at the call site:
```tsx
function Card(props: { title: string; renderLink: () => React.ReactNode }) {
return (
<div>
<h2>{props.title}</h2>
{props.renderLink()}
</div>
)
}
// Link narrowed to exactly /posts — no union check
;<Card title="All Posts" renderLink={() => <Link to="/posts">View</Link>} />
```
## Render Optimizations
### Fine-Grained Selectors with `select`
```tsx
function PostTitle() {
// Only re-renders when page changes, not when other search params change
const page = Route.useSearch({ select: ({ page }) => page })
return <span>Page {page}</span>
}
```
### Structural Sharing
Preserve referential identity across re-renders for search params:
```tsx
const router = createRouter({
routeTree,
defaultStructuralSharing: true, // Enable globally
})
// Or per-hook
const result = Route.useSearch({
select: (search) => ({ foo: search.foo, label: `Page ${search.foo}` }),
structuralSharing: true,
})
```
Structural sharing only works with JSON-compatible data. TypeScript will error if you return class instances with `structuralSharing: true`.
## Common Mistakes
### 1. CRITICAL: Adding type annotations or casts to inferred values
```tsx
// WRONG — casting masks real type errors
const search = useSearch({ from: '/posts' }) as { page: number }
// WRONG — unnecessary annotation
const params: { postId: string } = useParams({ from: '/posts/$postId' })
// WRONG — generic param on hook
const data = useLoaderData<{ posts: Post[] }>({ from: '/posts' })
// CORRECT — let inference work
const search = useSearch({ from: '/posts' })
const params = useParams({ from: '/posts/$postId' })
const data = useLoaderData({ from: '/posts' })
```
### 2. HIGH: Using un-narrowed `LinkProps` type
```tsx
// WRONG — LinkProps is a massive union, causes severe TS slowdown
const myProps: LinkProps = { to: '/posts' }
// CORRECT — use as const satisfies for precise inference
const myProps = { to: '/posts' } as const satisfies LinkProps
```
### 3. HIGH: Not narrowing `Link`/`useNavigate` with `from`
```tsx
// WRONG — search is a union of ALL routes, TS check grows with route count
<Link to=".." search={{ page: 0 }} />
// CORRECT — narrowed, fast check
<Link from={Route.fullPath} to=".." search={{ page: 0 }} />
```
### 4. CRITICAL (cross-skill): Missing router type registration
```tsx
// WRONG — Link/useNavigate have no autocomplete, all paths are untyped strings
const router = createRouter({ routeTree })
// (no declare module)
// CORRECT — always register
const router = createRouter({ routeTree })
declare module '@tanstack/react-router' {
interface Register {
router: typeof router
}
}
```
### 5. CRITICAL (cross-skill): Wrong-framework imports and file structure
Wrong-framework code looks plausible (it's React) but breaks the build or produces conflicting `/` routes at runtime.
```tsx
// WRONG — react-router-dom and next/* are different libraries
import { Link, useNavigate, useSearchParams } from 'react-router-dom'
import Link from 'next/link'
import { useRouter, useParams } from 'next/navigation'
// CORRECT — all routing exports come from @tanstack/react-router
import {
Link,
Outlet,
useNavigate,
useRouter,
useLocation,
useParams,
redirect,
} from '@tanstack/react-router'
```
```tsx
// WRONG file structures + APIs:
// src/pages/*.tsx with getServerSideProps / getStaticProps (Next.js Pages Router)
// app/layout.tsx + app/page.tsx (Next.js App Router)
// _app/index.tsx, pages/_app.tsx, pages/_document.tsx (Next.js custom App)
// loader/action exports (Remix)
// CORRECT — TanStack file-based routing at src/routes/*.tsx
export const Route = createFileRoute('/posts')({
loader: async () => { ... },
validateSearch: zodValidator(schema),
component: PostsComponent,
})
const search = Route.useSearch()
```
If a build error mentions `react-router-dom`, `next/`, `pages/_app`, or duplicate `/` routes, fix the import — don't paper over with type assertions.
### 6. CRITICAL: Treating typecheck as proof of runtime schema propagation
Types can say a field exists while a database projection, API serializer, or server function omits it. When adding or renaming a field, trace the value through storage, validation, handler output, loader data, and rendered UI. Do not cast the response to the desired type.
Add a runtime assertion against the real handler or serialized response, such as `expect(await getOrder({ data: { id } })).toMatchObject({ totalCents: 2599 })`.
Then run the route-level test and production build. The type test remains necessary, but it is not the runtime contract test.
See also: router-core (Register setup), router-core/navigation (from narrowing), router-core/code-splitting (getRouteApi).
© TanStack · MIT · TanStack/router