tanstack-vue-router-skilld — скилл для Claude Code
Скилл tanstack-vue-router-skilld для работы с @tanstack/vue-router — типобезопасным роутером Vue. Учит агента правилам настройки, file-based маршрутов, композаблов с Ref, линков и лоадеров.
MIT 101 установок ★ 186 обновлён 2026-10-10
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a claude-codeЧто делает 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-code2Вручную: положить файлы
~/.claude/skills/tanstack-vue-router-skilld/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/tanstack-vue-router-skilld/
1Через Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a codex2Вручную: положить файлы
.agents/skills/tanstack-vue-router-skilld/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a cursor2Вручную: положить файлы
.cursor/skills/tanstack-vue-router-skilld/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install skilld-dev/vue-ecosystem-skills skills/tanstack-vue-router-skilld2Вручную: положить файлы
.github/skills/tanstack-vue-router-skilld/SKILL.md1Через Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a gemini-cli2Командой платформы
gemini skills install https://github.com/skilld-dev/vue-ecosystem-skills --path skills/tanstack-vue-router-skilldВручную: положить файлы
.devin/skills/tanstack-vue-router-skilld/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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