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

tanstack-vue-router-skilld — скилл для Claude Code

Скилл tanstack-vue-router-skilld для работы с @tanstack/vue-router — типобезопасным роутером Vue. Учит агента правилам настройки, file-based маршрутов, композаблов с Ref, линков и лоадеров.

MIT 101 установок ★ 186 обновлён 2026-10-10

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

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

Скилл подсказывает, что большинство композаблов возвращают Ref<T> (в скрипте нужен .value, в шаблоне авторазворачивание), а useRouter(), useNavigate(), useLinkProps() и useAwaited() — обычные значения. Объясняет, что типобезопасность требует регистрации роутера через интерфейс Register, без неё Link и useNavigate принимают любую строку. Запрещает импорты из vue-router и использование <router-view>.

Внутри — правила для file-based роутинга через @tanstack/router-plugin, настройки Vite с vue() и vueJsx(), таблица композаблов, семантика Link с activeProps, работа beforeLoad/loader (Vue-композаблы в них не работают, стейт передаётся через контекст роутера), компоненты <Outlet>, <Navigate>, <Await>, SSR-хуки. Требует Vue 3.3+, Node 20.19+, только ESM. Версия библиотеки 1.170.35.

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

  • настроить типобезопасный роутинг в Vue 3 с автоподстановкой путей
  • объяснить агенту, какие композаблы возвращают Ref, а какие нет
  • избежать импортов из vue-router в проекте на TanStack Router
  • научить агента работать с file-based маршрутами через плагин Vite
  • показать, как правильно настроить beforeLoad и loader без Vue-композаблов внутри

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

  • Создай роут /posts/:id с лоадером, который подгружает пост по id из API
  • Настрой file-based роутинг через @tanstack/router-plugin в vite.config.ts
  • Добавь <Link> на /dashboard с активным классом current-page

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

1Через Skills CLI (Vercel)

npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a claude-code

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

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

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

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

Вопросы о tanstack-vue-router-skilld

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

Выполни npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a claude-code, файл скилла окажется в ~/.claude/skills/tanstack-vue-router-skilld/SKILL.md.

Что делает tanstack-vue-router-skilld?

Скилл учит агента работать с @tanstack/vue-router: регистрировать роутер для типобезопасности, использовать композаблы с Ref, настраивать file-based маршруты, писать лоадеры и хуки без Vue-композаблов внутри.

Какие композаблы возвращают Ref?

Почти все, кроме useRouter(), useNavigate(), useLinkProps() и useAwaited(). useSearch(), useParams(), useLoaderData(), useRouteContext() и остальные возвращают Ref<T> — в скрипте нужен .value.

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

SKILL.md · MIT
---
name: tanstack-vue-router-skilld
description: Use when writing, debugging, or refactoring code that imports @tanstack/vue-router (TanStack Router for Vue). Covers setup, file-based and code-based routes, composables returning Ref, Link, loaders, search params, SSR, and v1.170.x deprecations.
license: MIT
---

# @tanstack/vue-router

Type-safe router for Vue. Prepared source: version **1.170.35** (`package.json:3`).

- Requires `vue >= 3.3.0` (peer), Node `>= 20.19` (`package.json:59-88`)
- Runtime deps: `@tanstack/[email protected]`, `@tanstack/[email protected]`, `@tanstack/vue-store@^0.11.0`
- ESM-only (`"type": "module"`), no `main`/CJS entry
- Entry points: `@tanstack/vue-router`, `@tanstack/vue-router/ssr/server`, `@tanstack/vue-router/ssr/client` (`package.json:29-50`)

Docs: https://tanstack.com/router (framework pages verified at `/router/latest/docs/framework/vue/...`)

## Hard rules

1. **Most composables return `Ref<T>`** — use `.value` in script; templates auto-unwrap. `useRouter()`, `useNavigate()`, `useLinkProps()`, `useAwaited()` do NOT return refs. Full table in [references/composables.md](./references/composables.md).
2. **Never cast or annotate inferred route/router types.** Types come from the route tree and the `Register` declaration.
3. **Register the router for type safety** — without this, `Link`/`useNavigate`/`useSearch` accept any string:

```ts
declare module '@tanstack/vue-router' {
  interface Register {
    router: typeof router
  }
}
```

4. **Not `vue-router`.** Never import `useRoute`/`useRouter` from `vue-router`, never use `<router-view>`/`<router-link>`.
5. **`beforeLoad`/`loader` are plain async functions.** Vue composables (`ref`, `computed`, lifecycle hooks) cannot run inside them. Pass state through router `context`.
6. Route options accept Vue SFCs: `component`, `errorComponent`, `notFoundComponent`, `pendingComponent` and the `default*Component` router options take `.vue` files or `h()`-style function components (`src/route.ts:54-58`, `src/router.ts:26-65`).

## Setup with Vite (file-based routing)

```bash
npm install @tanstack/vue-router
npm install -D @tanstack/router-plugin @vitejs/plugin-vue @vitejs/plugin-vue-jsx
```

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({ target: 'vue', autoCodeSplitting: true }), // before vue()
    vue(),
    vueJsx(), // needed for .tsx route files
  ],
})
```

Source: official Vue example, https://github.com/TanStack/router/blob/main/examples/vue/basic-file-based-sfc/vite.config.ts

```ts
// src/main.ts
import { createApp, h } from 'vue'
import { RouterProvider, createRouter } from '@tanstack/vue-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
  scrollRestoration: true,
})

declare module '@tanstack/vue-router' {
  interface Register {
    router: typeof router
  }
}

createApp({ setup: () => () => h(RouterProvider, { router }) }).mount('#app')
```

File naming, split-file conventions (`.route.ts`, `.component.vue`, `.lazy.ts`), and the generated `routeTree.gen.ts`: [references/file-based-routing.md](./references/file-based-routing.md).

## Code-based routing

```ts
import { h } from 'vue'
import { createRootRouteWithContext, createRoute, createRouter, Outlet } from '@tanstack/vue-router'

interface RouterContext { auth: { isAuthenticated: boolean } }

const rootRoute = createRootRouteWithContext<RouterContext>()({ component: () => h(Outlet) })

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'posts',
  loader: ({ context }) => fetchPosts(context.auth),
})

const routeTree = rootRoute.addChildren([postsRoute])
const router = createRouter({
  routeTree,
  context: { auth: { isAuthenticated: false } },
})
```

Route options, hooks on route objects, and property-order rules: [references/routes.md](./references/routes.md).

## Composables

| Composable | Returns | Notes |
|---|---|---|
| `useRouter()` | router instance | not a ref |
| `useRouterState({ select })` | `Ref<T>` | pass `select` to avoid re-renders |
| `useNavigate({ from? })` | function | not a ref |
| `useSearch({ from })` | `Ref<T>` | throws unless `from` matches |
| `useParams({ from })` | `Ref<T>` | |
| `useMatch({ from })` | `Ref<T>` | |
| `useLoaderData({ from })` | `Ref<T>` | |
| `useLoaderDeps({ from })` | `Ref<T>` | |
| `useRouteContext({ from })` | `Ref<T>` | |
| `useLocation()` | `Ref<ParsedLocation>` | |
| `useMatches()` / `useParentMatches()` / `useChildMatches()` | `Ref<Array<Match>>` | accepts `select` |
| `useMatchRoute()` | function | calling it returns `Ref<false \| params>` (`src/Matches.tsx:148-172`) |
| `useLinkProps(options)` | link props object | for custom anchors |
| `useBlocker({ shouldBlockFn })` | `void` or `Ref<BlockerResolver>` | resolver only with `withResolver: true` |
| `useCanGoBack()` | `Ref<boolean>` | `location.state.__TSR_index !== 0` (`src/useCanGoBack.ts:4-10`) |
| `useAwaited({ promise })` | `[data, promise]` tuple | for deferred data |

Route objects and `getRouteApi('/path')` expose the same hooks pre-scoped: `Route.useSearch()`, `Route.useLoaderData()`, `Route.useNavigate()`, `Route.Link` (`src/route.ts:72-80`).

Details and `select`/`strict` semantics: [references/composables.md](./references/composables.md).

## Components

| Component | Purpose |
|---|---|
| `<RouterProvider :router="router" />` | mounts the router; extra attrs update router options (`src/RouterProvider.tsx:60-95`) |
| `<Link to="..." :params="..." :search="...">` | type-safe anchor; active state sets `data-status="active"` + `aria-current="page"` (`src/link.tsx:522-525`); default slot receives `{ isActive }` (`src/link.tsx:918`) |
| `<Outlet />` | renders matched child route (`src/Match.tsx:275`) |
| `<Navigate to="..." />` | declarative redirect, fires in `onMounted` (`src/useNavigate.tsx:24-40`) |
| `<MatchRoute to="..." :fuzzy="true">` | renders slot when matched; scoped slot receives params |
| `<Await :promise="p">` | deferred data with `<Suspense>` (`src/awaited.tsx:26-43`) |
| `<Block :should-block-fn="fn">` | navigation blocking; scoped slot receives resolver (`src/useBlocker.tsx:470-491`) |
| `<CatchBoundary>` / `<ErrorComponent>` | error boundary via `onErrorCaptured` |
| `<ClientOnly>` | renders children only after mount |
| `<HeadContent>`, `<Scripts>`, `<Html>`, `<Body>`, `<Asset>`, `<ScriptOnce>` | SSR document shell |

Link options, `activeProps` (defaults to `{ class: 'active' }`, `src/link.tsx:477`), preloading (`intent`/`viewport`/`render`), `linkOptions()`, and `createLink()`: [references/navigation-links.md](./references/navigation-links.md).

## Data loading and redirects

```ts
const route = createFileRoute('/posts/$postId')({
  beforeLoad: async ({ context, params }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: '/login', search: { from: params.postId } })
    }
  },
  loaderDeps: ({ search: { page } }) => ({ page }),
  loader: ({ deps, params }) => fetchPost(params.postId, deps.page),
  pendingComponent: PendingSpinner, // .vue file works too
})
```

`throw redirect()`, `isRedirect()`, deferred streaming with `defer()`, and context typing: [references/data-loading.md](./references/data-loading.md).

## Search params

```ts
import { z } from 'zod' // or plain validators
const route = createFileRoute('/posts')({
  validateSearch: z.object({ page: z.number().default(1) }),
  search: {
    middlewares: [stripSearchParams({ page: 1 })],
  },
})
```

Validators, input/output schemas, `retainSearchParams`/`stripSearchParams`, and custom serialization: [references/search-params.md](./references/search-params.md).

## Deprecations in 1.170.x (use instead)

| Deprecated | Replacement | Proof |
|---|---|---|
| `Route`, `RootRoute`, `FileRoute`, `RouteApi` classes | `createRoute`, `createRootRoute`, `createFileRoute`, `getRouteApi` | `src/route.ts:95`, `src/route.ts:220`, `src/route.ts:460`, `src/fileRoute.ts:57` |
| `rootRouteWithContext` | `createRootRouteWithContext` | `src/route.ts:414` |
| `NotFoundRoute` / `routerOptions.notFoundRoute` | `notFoundComponent` route option / `defaultNotFoundComponent` router option | https://tanstack.com/router/latest/docs/framework/vue/guide/not-found-errors |
| `<ScrollRestoration />` | `scrollRestoration: true` in `createRouter` | `src/ScrollRestoration.tsx:18` |
| `opts.navigate` in `beforeLoad`/`loader` | `throw redirect({ to })` | https://tanstack.com/router/latest/docs/framework/vue/api/router/RouteOptionsType |
| `parseParams`/`stringifyParams` | `params.parse`/`params.stringify` | same RouteOptionsType doc |
| `preSearchFilters`/`postSearchFilters` | `search.middlewares` | same RouteOptionsType doc |
| `FileRouteLoader` / separate `.lazy.ts` loader files | keep the loader in the route file | `src/fileRoute.ts:153` |
| `useBlocker(fn, condition)` legacy signatures | `{ shouldBlockFn }` object | `src/useBlocker.tsx:139-151` |

## Best practices

- Set `defaultPreload: 'intent'` on the router; preloaded data is cached (default 30 s, `defaultPreloadMaxAge`) — https://tanstack.com/router/latest/docs/framework/vue/guide/preloading
- In `loaderDeps`, select only the search params the loader uses; spreading all of `search` re-runs the loader on every unrelated param change — https://tanstack.com/router/latest/docs/framework/vue/guide/data-loading
- Use `getRouteApi('/posts/$postId')` in deep components instead of importing the `Route` object (avoids circular imports) — https://tanstack.com/router/latest/docs/framework/vue/guide/data-loading
- When re-throwing from `beforeLoad` error handlers, check `isRedirect(error)` first so redirects are not swallowed — https://tanstack.com/router/latest/docs/framework/vue/guide/authenticated-routes
- Route option order is inference-sensitive (`validateSearch`/`params` before `loaderDeps`, `beforeLoad` before `loader`); the `create-route-property-order` ESLint rule is auto-fixable — https://tanstack.com/router/latest/docs/framework/vue/eslint/create-route-property-order
- Prefer `linkOptions({ to, ... })` over bare object literals for reusable navigation targets; works in `<Link>`, `navigate()`, `redirect()` — https://tanstack.com/router/latest/docs/framework/vue/guide/link-options
- With `select` returning new objects in hooks, enable `defaultStructuralSharing: true` on the router — https://tanstack.com/router/latest/docs/framework/vue/guide/render-optimizations
- External links with protocols outside `protocolAllowlist` (default `DEFAULT_PROTOCOL_ALLOWLIST`) are blocked to prevent XSS (`src/link.tsx:543-550`)

## References

- [references/api-surface.md](./references/api-surface.md) — every public export, grouped
- [references/composables.md](./references/composables.md) — hook signatures and `Ref` semantics
- [references/routes.md](./references/routes.md) — route creation, options, route hooks
- [references/navigation-links.md](./references/navigation-links.md) — `Link`, navigation, blocking, preloading
- [references/data-loading.md](./references/data-loading.md) — loaders, context, redirects, deferred data
- [references/search-params.md](./references/search-params.md) — validation and middlewares
- [references/file-based-routing.md](./references/file-based-routing.md) — Vite plugin, naming, code splitting
- [references/ssr.md](./references/ssr.md) — server entry points and document shell components

© skilld-dev · MIT · skilld-dev/vue-ecosystem-skills

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

Все скиллы по теме «Фронтенд и UI» →
vue-router-best-practices github.com/vuejs-ai Скилл vue-router-best-practices для Claude Code обучает правилам Vue Router 4: навигационным гвардам, параметрам маршрутов и синхронизации с жизненным циклом компонента. Помогает избежать редиректов и утечек памяти. CX Codex +1 16 700установок tanstack-router tanstack-skills Скилл по TanStack Router для React и Solid: файловый роутинг, поисковые параметры и загрузка данных с проверкой типов. CX Codex +1 5 200установок vue-typescript Mindrally Скилл vue-typescript для Claude Code задаёт правила генерации кода на Vue 3 и TypeScript с Vite, Pinia и Tailwind, включая синтаксис и оптимизацию загрузки. CX Codex +1 832установок clerk-tanstack-patterns clerk Скилл clerk-tanstack-patterns для Claude Code подсказывает, как настроить авторизацию Clerk в TanStack React Start. Активируется при работе с createServerFn, защитой маршрутов через beforeLoad и middleware. CX Codex +1 16 400установок tanstack-start oakoss По TanStack Start описывает серверные функции, SSR со стримингом, middleware и деплой. CX Codex +1 156установок tanstack-cli oakoss Скилл tanstack-cli настраивает сборку библиотек через TanStack Config и Vite с генерацией типов и релизом через conventional commits. CX Codex +1 115установок

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

Весь набор →
floating-ui-vue-skilld Скилл floating-ui-vue-skilld помогает писать позиционирование всплывающих окон, тултипов и меню через @floating-ui/vue 2.0.1 во Vue 3.3+. CX Codex +1 119установок vue-data-ui-skilld Скилл vue-data-ui-skilld помогает агенту работать с библиотекой графиков vue-data-ui для Vue 3: выбирать компоненты, настраивать темы и разбирать ошибки. CX Codex +1 118установок unovis-vue-skilld Скилл unovis-vue-skilld для Claude Code помогает писать и отлаживать код на Vue 3 с компонентами @unovis/vue. Используется для построения графиков и обновления интеграции с Unovis 1.7.0. CX Codex +1 112установок vitepress-skilld Скилл vitepress-skilld даёт агенту справочник по API, настройкам и CLI VitePress 1.6.4 при сборке сайтов документации. CX Codex +1 110установок tanstack-ai-vue-skilld Скилл tanstack-ai-vue-skilld помогает писать и отлаживать Vue 3-код с @tanstack/ai-vue: чат, генерация медиа и типизированные инструменты. CX Codex +1 110установок formkit-core-skilld Скилл formkit-core-skilld для Claude Code помогает писать, отлаживать и проверять код для @formkit/core: узлов, значений, событий и хуков. CX Codex +1 105установок unhead-vue-skilld Скилл unhead-vue-skilld помогает ИИ-агенту настраивать теги head, метаданные SEO и скрипты в проектах на Vue 3 через библиотеку @unhead/vue. CX Codex +1 105установок tanstack-vue-store-skilld Скилл tanstack-vue-store-skilld для Claude Code направляет агента при разработке стейт-менеджмента на @tanstack/vue-store в проектах на Vue. Подключается при импорте библиотеки и настройке хранилищ. CX Codex +1 100установок

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

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