К основному содержанию
скилл CX Codex

tanstack-router · oakoss — скилл для Claude Code: что делает и как установить

Скилл tanstack-router настраивает типобезопасную файловую маршрутизацию в React через @tanstack/react-router. Помогает с лоадерами данных, валидацией параметров поиска и разделением кода.

MIT 150 установок ★ 29 обновлён 2026-08-17

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add oakoss/agent-skills --skill tanstack-router -a claude-code
Открыть на GitHub

Что делает tanstack-router

Скилл обучает ассистента архитектуре @tanstack/react-router версии 1.3 и плагина @tanstack/router-plugin. Он подсказывает рабочие шаблоны для вызова createFileRoute, отложенной загрузки через createLazyFileRoute, валидации searchParams схемой zodValidator и работы с контекстом роутов.

В конфигурации Vite плагин TanStackRouterVite обязан стоять строго до вызова react(), иначе генерация дерева маршрутов сломается. Скилл также предотвращает типовые баги: запрещает вызов prefetchQuery внутри роут-лоадеров в пользу ensureQueryData и заменяет запросы из useEffect на параллельную загрузку данных через Promise.all.

Какие задачи решает

  • Сконфигурировать файловый роутинг в Vite с плагином @tanstack/router-plugin
  • Валидировать параметры URL через схемы zodValidator
  • Настроить загрузку данных в роутах через ensureQueryData из TanStack Query
  • Защитить маршруты авторизацией с помощью _authenticated.tsx и хука beforeLoad

Примеры запросов агенту

  • Сделай маршрут posts.$postId.tsx с лоадером данных и валидацией search params
  • Добавь блокировку ухода со страницы через useBlocker для формы с несохранёнными данными
  • Настрой код-сплиттинг для страницы dashboard.lazy.tsx

Как установить tanstack-router

1Через Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill tanstack-router -a claude-code

2Вручную: положить файлы

~/.claude/skills/tanstack-router/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/tanstack-router/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о tanstack-router

Как установить tanstack-router в Claude Code?

Выполните в терминале команду npx skills add oakoss/agent-skills --skill tanstack-router -a claude-code. Файл навыка сохранится по пути ~/.claude/skills/tanstack-router/SKILL.md.

Что делает скилл tanstack-router?

Он передаёт агенту правила построения файловых маршрутов, валидации параметров поиска и привязки TanStack Query. Ассистент перестаёт делать сетевые вызовы в useEffect и организует загрузку данных прямо в роутере.

Почему в лоадерах роутов используется ensureQueryData вместо prefetchQuery?

Метод prefetchQuery возвращает void и глушит ошибки сетевых запросов. Лоадеру нужен ensureQueryData, потому что он возвращает данные в компонент и корректно выбрасывает исключение при сбое.

Исходный текст

SKILL.md · MIT
---
name: tanstack-router
description: 'Type-safe, file-based React routing with route loaders, search params validation, code splitting, preloading, navigation, route context, and TanStack Query integration. Use when setting up file-based routing, adding search params validation, implementing route loaders, code splitting routes, configuring virtual file routes, protecting routes with auth guards, or fixing type registration errors. Use for router setup, navigation patterns, URL state management, data loading.'
license: MIT
metadata:
  author: oakoss
  version: '1.3'
  source: 'https://tanstack.com/router/latest/docs'
user-invocable: false
---

# TanStack Router

Type-safe, file-based routing for React with route-level data loading, search params validation, code splitting, and TanStack Query integration.

**Package:** `@tanstack/react-router` | **Plugin:** `@tanstack/router-plugin`

## Quick Reference

| Pattern                           | Usage                                   |
| --------------------------------- | --------------------------------------- |
| `createFileRoute('/path')`        | Define file-based route                 |
| `createRootRouteWithContext<T>()` | Root route with typed context           |
| `createLazyFileRoute('/path')`    | Code-split route component              |
| `zodValidator(schema)`            | Search params validation                |
| `Route.useLoaderData()`           | Access loader data in component         |
| `Route.useParams()`               | Type-safe route params                  |
| `Route.useSearch()`               | Type-safe search params                 |
| `useNavigate()`                   | Programmatic navigation                 |
| `useBlocker()`                    | Block navigation (dirty forms)          |
| `notFound()`                      | Throw 404 from loader                   |
| `getRouteApi('/path')`            | Type-safe hooks in split files          |
| `stripSearchParams(defaults)`     | Clean default values from URLs          |
| `retainSearchParams(['key'])`     | Preserve params across navs             |
| `useAwaited({ promise })`         | Suspend until deferred promise resolves |
| `useCanGoBack()`                  | Check if router can go back safely      |

## Data Loading

| Method               | Returns | Throws | Use Case                                         |
| -------------------- | ------- | ------ | ------------------------------------------------ |
| `ensureQueryData`    | Data    | Yes    | Route loaders (recommended)                      |
| `prefetchQuery`      | void    | No     | Background prefetching                           |
| `fetchQuery`         | Data    | Yes    | Immediate data need                              |
| `defer()` (optional) | Promise | No     | Stream non-critical data (promises auto-handled) |

## Preloading

| Strategy     | Behavior                  | Use Case                    |
| ------------ | ------------------------- | --------------------------- |
| `'intent'`   | Preload on hover/focus    | Default for most links      |
| `'render'`   | Preload when Link mounts  | Critical next pages         |
| `'viewport'` | Preload when Link in view | Below-fold content          |
| `false`      | No preloading             | Heavy, rarely-visited pages |

## File Organization

| File                 | Purpose                      |
| -------------------- | ---------------------------- |
| `__root.tsx`         | Root route with `<Outlet />` |
| `index.tsx`          | Index route for `/`          |
| `posts.$postId.tsx`  | Dynamic param route          |
| `_authenticated.tsx` | Pathless layout (auth guard) |
| `dashboard.lazy.tsx` | Code-split component         |

## Common Mistakes

| Mistake                           | Fix                                                   |
| --------------------------------- | ----------------------------------------------------- |
| Missing router type registration  | Add `declare module` with `Register` interface        |
| `useParams()` without `from`      | Always pass `from: '/route/path'` for exact types     |
| `useNavigate()` for regular links | Use `<Link>` for `<a>` tags, a11y, preloading         |
| `prefetchQuery` in loaders        | Use `ensureQueryData` (returns data, throws errors)   |
| Fetching in `useEffect`           | Use route loaders (prevents waterfalls)               |
| Sequential fetches in loader      | Use `Promise.all` for parallel requests               |
| Missing leading slash             | Always `'/about'` not `'about'`                       |
| TanStackRouterVite after react()  | Plugin MUST come before `react()` in Vite config      |
| `strict: false` params unparsed   | Use strict mode or manually parse after navigation    |
| Pathless route notFoundComponent  | Define `notFoundComponent` on child routes instead    |
| Aborted loader undefined error    | Guard `errorComponent` with `if (!error) return null` |
| No `loaderDeps` declared          | Declare deps so loader only re-runs when they change  |

## Delegation

- **TanStack Query patterns** — data fetching, caching, mutations: use `tanstack-query` skill
- **TanStack Start** — server functions, SSR, server-side auth: use `tanstack-start` skill
- **TanStack Table** — table rendering with router search params: use `tanstack-table` skill
- **Router + Query integration** — loader data flow, preloading: see [Loader Data Flow Patterns](references/loader-query-patterns.md)

> If the `tanstack-devtools` skill is available, delegate router state debugging and route tree inspection to it.

## References

- [Setup](references/setup.md) — installation, Vite config, file structure, app setup, router default options
- [Type Safety](references/type-safety.md) — register router, `from` param, `strict: false`, type utilities, getRouteApi
- [Data Loading](references/data-loading.md) — route loaders, Query integration, parallel loading, streaming, deferred data, abort signal, loaderDeps
- [Search Params](references/search-params.md) — validation, strip/retain middleware, fine-grained subscriptions, debounce, custom serializers
- [Navigation](references/navigation.md) — Link, active styling, relative navigation, hash, route masks, blocker, scroll restoration
- [Auth and Context](references/auth-and-context.md) — beforeLoad, context inheritance, pathless layouts, dependency injection, error handling
- [Code Splitting](references/code-splitting.md) — lazy routes, auto splitting, preloading strategies, programmatic preloading
- [Virtual File Routes](references/virtual-routes.md) — rootRoute, route, index, layout, physical builders, mixing file-based and code-based routing
- [Known Issues](references/known-issues.md) — 20 documented issues with fixes, anti-patterns
- [Loader+Query Patterns](references/loader-query-patterns.md) — ensureQueryData in loaders, parallel loading, critical vs non-critical data, search-param-dependent loaders

© oakoss · MIT · oakoss/agent-skills

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →

Сначала — tanstack-router от других авторов.

tanstack-router tanstack-skills Скилл по TanStack Router для React и Solid: файловый роутинг, поисковые параметры и загрузка данных с проверкой типов. CX Codex +1 5 200установок tanstack-router Claude Skills Maintainers Скилл tanstack-router настраивает типобезопасный роутинг на базе файлов в React и помогает связать его с TanStack Query или Cloudflare Workers. CX Codex +1 468установок tanstack-router-best-practices DeckardGer Скилл tanstack-router-best-practices для Claude Code: правила по TanStack Router для React — типизация, загрузка данных, search params и навигация. Структурирует роутинг в растущих проектах. CX Codex +1 7 200установок react-router TanStack Скилл для агента по @tanstack/react-router: справочник хуков и компонентов плюс сборка файлового роутинга на Vite от установки до routeTree.gen. CX Codex +1 657установок tanstack-router-react-cursorrules-prompt-file PatrickJS Правило tanstack-router-react-cursorrules-prompt-file задаёт стандарты TanStack Router v1 в React: файловую маршрутизацию, валидацию search-параметров схемами Zod, загрузчики данных и защиту маршрутов через beforeLoad. CX Codex +1 ★ 41 178звёзд репо router-core TanStack Скилл router-core по TanStack Router направляет задачу к нужному подскиллу и напоминает о выводе типов и клиентских лоадерах. CX Codex +1 711установок react-tanstack-router-query PatrickJS Правило react-tanstack-router-query настраивает связку TanStack Router v1 и TanStack Query v5 в React-проектах для загрузки данных в роутере без спиннеров ожидания. CX Codex +1 ★ 41 178звёзд репо tanstack-vue-router-skilld skilld-dev Скилл tanstack-vue-router-skilld для работы с @tanstack/vue-router — типобезопасным роутером Vue. Учит агента правилам настройки, file-based маршрутов, композаблов с Ref, линков и лоадеров. CX Codex +1 101установок

Из того же набора106

Весь набор →
tanstack-table Настраивает headless-таблицы TanStack Table v8 в React: серверная пагинация, фильтры и сортировка без циклических ререндеров. CX Codex +1 155установок changesets Скилл changesets помогает вести версии и changelog пакетов в монорепозитории. Он пригодится для согласованных релизов и публикации пакетов в npm. CX Codex +1 154установок opentofu Помогает писать и проверять конфигурации OpenTofu и Pulumi. Помогает управлять инфраструктурой, состоянием и окружениями из кода. CX Codex +1 153установок arktype-validation Скилл arktype-validation для Claude Code описывает схемы ArkType строками в синтаксисе TypeScript, включая морфы и рантайм-валидацию данных и переменных окружения через ArkEnv. CX Codex +1 153установок api-testing Скилл api-testing для Claude Code помогает писать интеграционные тесты REST API и проверять ответы эндпоинтов. Включается при настройке HTTP-моков или тестировании ошибок. CX Codex +1 149установок github-actions Помогает создавать и настраивать GitHub Actions workflows: от триггеров и матриц сборки до кеширования и аутентификации. Автоматизирует тесты, релизы и развёртывание. CX Codex +1 149установок git-workflow Скилл git-workflow помогает агенту выстраивать trunk-based разработку, оформлять conventional commits, настраивать пайплайны GitHub Actions и чистить историю Git. CX Codex +1 149установок ux-designer Скилл ux-designer для ИИ-агентов: проводит проект от информационной архитектуры до передачи в разработку, с проверкой доступности и юзабилити. CX Codex +1 148установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой