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
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a claude-codeWhat 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-routerimports in a TanStack Router project - show how to configure file-based routes through the Vite plugin
- write
beforeLoadandloadercorrectly without Vue composables inside
Example prompts for the agent
- Create a
/posts/:idroute with a loader that fetches the post byidfrom the API - Set up file-based routing via
@tanstack/router-plugininvite.config.ts - Add a
<Link>to/dashboardwith the active classcurrent-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-code2Manually: put the files in place
~/.claude/skills/tanstack-vue-router-skilld/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tanstack-vue-router-skilld/
1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a codex2Manually: put the files in place
.agents/skills/tanstack-vue-router-skilld/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a cursor2Manually: put the files in place
.cursor/skills/tanstack-vue-router-skilld/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install skilld-dev/vue-ecosystem-skills skills/tanstack-vue-router-skilld2Manually: put the files in place
.github/skills/tanstack-vue-router-skilld/SKILL.md1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a gemini-cli2Platform CLI
gemini skills install https://github.com/skilld-dev/vue-ecosystem-skills --path skills/tanstack-vue-router-skilldManually: put the files in place
.devin/skills/tanstack-vue-router-skilld/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilld -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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