Skip to main content
skill CX Codex

tanstack-vue-router-skilld — Claude Code skill for TanStack Vue Router

tanstack-vue-router-skilld — a skill for working with @tanstack/vue-router, the type-safe Vue router. Teaches the agent setup rules, file-based routes, composables returning Ref, links and loaders.

MIT 101 installs ★ 186 updated 2026-10-10

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a claude-code
Open on GitHub

What tanstack-vue-router-skilld does

The skill explains that most composables return Ref<T> (.value in script, auto-unwrap in templates), while useRouter(), useNavigate(), useLinkProps() and useAwaited() give plain values. Shows that type safety requires registering the router through the Register interface; without it, Link and useNavigate accept any string. Forbids imports from vue-router and <router-view> usage.

Inside: file-based routing via @tanstack/router-plugin, Vite setup with vue() and vueJsx(), composable reference table, Link semantics with activeProps, how beforeLoad/loader work (Vue composables cannot run inside them, pass state through router context), components <Outlet>, <Navigate>, <Await>, SSR hooks. Requires Vue 3.3+, Node 20.19+, ESM only. Library version 1.170.35.

What it helps with

  • set up type-safe routing in Vue 3 with path autocompletion
  • teach the agent which composables return Ref and which do not
  • prevent vue-router imports in a TanStack Router project
  • show how to configure file-based routes through the Vite plugin
  • write beforeLoad and loader correctly without Vue composables inside

Example prompts for the agent

  • Create a /posts/:id route with a loader that fetches the post by id from the API
  • Set up file-based routing via @tanstack/router-plugin in vite.config.ts
  • Add a <Link> to /dashboard with the active class current-page

How to install tanstack-vue-router-skilld

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/tanstack-vue-router-skilld/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tanstack-vue-router-skilld

How do I install tanstack-vue-router-skilld in Claude Code?

Run npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a claude-code, the skill file lands in ~/.claude/skills/tanstack-vue-router-skilld/SKILL.md.

What does tanstack-vue-router-skilld do?

The skill teaches the agent to work with @tanstack/vue-router: register the router for type safety, use composables with Ref, configure file-based routes, write loaders and hooks without Vue composables inside.

Which composables return Ref?

Almost all, except useRouter(), useNavigate(), useLinkProps() and useAwaited(). useSearch(), useParams(), useLoaderData(), useRouteContext() and the rest return Ref<T> — you need .value in script.

Source text

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

Similar skills

All skills for Frontend and UI →

From the same set32

The whole set →
floating-ui-vue-skilld floating-ui-vue-skilld guides AI coding agents on anchoring tooltips, popovers, and menus using @floating-ui/vue 2.0.1 in Vue 3.3+. CX Codex +1 119installs vue-data-ui-skilld The vue-data-ui-skilld skill guides agents working with the vue-data-ui Vue 3 chart library, from component selection and theming to SSR and debugging. CX Codex +1 118installs unovis-vue-skilld unovis-vue-skilld is a Claude Code skill for building and debugging Vue 3 code with @unovis/vue, including chart work and migration to API 1.7.0. CX Codex +1 112installs vitepress-skilld vitepress-skilld supplies API specs, config references, and CLI instructions for VitePress 1.6.4. CX Codex +1 110installs tanstack-ai-vue-skilld The tanstack-ai-vue-skilld skill guides Vue 3 work with @tanstack/ai-vue, covering streaming chat, media generation, reactive state, and typed client tools. CX Codex +1 110installs formkit-core-skilld formkit-core-skilld is a Claude Code skill for writing, debugging, and checking code that uses FormKit core nodes, values, events, and hooks. CX Codex +1 105installs unhead-vue-skilld unhead-vue-skilld guides AI coding agents through document head management, SEO metadata, and script loading in Vue 3 applications via @unhead/vue. CX Codex +1 105installs tanstack-vue-store-skilld tanstack-vue-store-skilld — a skill for Claude Code that guides state management implementations using @tanstack/vue-store. Triggers whenever components import code from the library in a Vue application. CX Codex +1 100installs

Project sponsors

Companies that keep this analytics open