vue-router
Vue bindings for TanStack Router: RouterProvider, useRouter, useRouterState, useMatch, useMatches, useLocation, useSearch, useParams, useNavigate, useLoaderData, useLoaderDeps, useRouteContext, useBlocker, useCanGoBack, Link, Navigate, Outlet, CatchBoundary, ErrorComponent, Html, Body. Vue-specific patterns with Ref<T> returns, defineComponent, h() render functions, provide/inject, and computed refs.
How do I install this agent skill?
npx skills add https://github.com/tanstack/router --skill vue-routerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides official documentation and setup instructions for the TanStack Vue Router library. All dependencies and commands are standard for development and originate from the official vendor.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Vue Router (@tanstack/vue-router)
This skill builds on router-core. Read @tanstack/router-core#router-core first for foundational concepts.
This skill covers the Vue-specific bindings, components, composables, and setup for TanStack Router.
CRITICAL: TanStack Router types are FULLY INFERRED. Never cast, never annotate inferred values.
CRITICAL: TanStack Router is CLIENT-FIRST. Loaders run on the client by default, not on the server.
CRITICAL: Most composables return
Ref<T>— access via.valuein script, auto-unwrapped in templates. This is the #1 difference from the React version.
CRITICAL: Do not confuse
@tanstack/vue-routerwithvue-router(the official Vue router). They are completely different libraries with different APIs.
Full Setup: File-Based Routing with Vite
1. Install Dependencies
npm install @tanstack/vue-router
npm install -D @tanstack/router-plugin @vitejs/plugin-vue-jsx
2. Configure Vite Plugin
// 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: [
// MUST come before vue()
tanstackRouter({
target: 'vue',
autoCodeSplitting: true,
}),
vue(),
vueJsx(), // Required for JSX/TSX route files
],
})
3. Create Root Route
// src/routes/__root.tsx
import { createRootRoute, Link, Outlet } from '@tanstack/vue-router'
export const Route = createRootRoute({
component: RootLayout,
})
function RootLayout() {
return (
<>
<nav>
<Link to="/" activeProps={{ class: 'font-bold' }}>
Home
</Link>
<Link to="/about" activeProps={{ class: 'font-bold' }}>
About
</Link>
</nav>
<hr />
<Outlet />
</>
)
}
4. Create Route Files
// src/routes/index.tsx
import { createFileRoute } from '@tanstack/vue-router'
export const Route = createFileRoute('/')({
component: HomePage,
})
function HomePage() {
return <h1>Welcome Home</h1>
}
5. Create Router Instance and Register Types
// src/main.tsx
import { createApp } from 'vue'
import { RouterProvider, createRouter } from '@tanstack/vue-router'
import { routeTree } from './routeTree.gen'
const router = createRouter({ routeTree })
// REQUIRED — without this, Link/useNavigate/useSearch have no type safety
declare module '@tanstack/vue-router' {
interface Register {
router: typeof router
}
}
const app = createApp(RouterProvider, { router })
app.mount('#root')
Composables Reference
All composables imported from @tanstack/vue-router. Most return Ref<T> — access via .value in script or auto-unwrap in templates.
useRouter() — returns TRouter (NOT a Ref)
import { useRouter } from '@tanstack/vue-router'
const router = useRouter()
router.invalidate()
useRouterState() — returns Ref<T>
Subscribe to router state changes. Exposes the entire state and thus incurs
a performance cost. For matches or location favor useMatches and useLocation.
import { useRouterState } from '@tanstack/vue-router'
const isLoading = useRouterState({ select: (s) => s.isLoading })
// Access: isLoading.value
useNavigate() — returns a function (NOT a Ref)
import { useNavigate } from '@tanstack/vue-router'
const navigate = useNavigate()
async function handleSubmit() {
await saveData()
navigate({ to: '/posts/$postId', params: { postId: '123' } })
}
useSearch({ from }) — returns Ref<T>
import { useSearch } from '@tanstack/vue-router'
const search = useSearch({ from: '/products' })
// Access: search.value.page
useParams({ from }) — returns Ref<T>
import { useParams } from '@tanstack/vue-router'
const params = useParams({ from: '/posts/$postId' })
// Access: params.value.postId
useLoaderData({ from }) — returns Ref<T>
import { useLoaderData } from '@tanstack/vue-router'
const data = useLoaderData({ from: '/posts/$postId' })
// Access: data.value.post.content
useMatch({ from }) — returns Ref<T>
import { useMatch } from '@tanstack/vue-router'
const match = useMatch({ from: '/posts/$postId' })
// Access: match.value.loaderData.post.title
Other Composables
useMatches()—Ref<Array<Match>>, all active route matchesuseRouteContext({ from })—Ref<T>, context frombeforeLoaduseBlocker({ shouldBlockFn })— blocks navigation for unsaved changesuseCanGoBack()—Ref<boolean>useLocation()—Ref<ParsedLocation>useLoaderDeps({ from })—Ref<T>, loader dependency valuesuseLinkProps()— returnsLinkHTMLAttributesuseMatchRoute()— returns a function; calling it returnsRef<false | Params>
Components Reference
RouterProvider
import { RouterProvider } from '@tanstack/vue-router'
// In createApp or template
<RouterProvider :router="router" />
Link
Type-safe navigation link with scoped slot for active state:
<Link to="/posts/$postId" :params="{ postId: '42' }">
View Post
</Link>
<!-- Scoped slot for active state -->
<Link to="/about">
<template #default="{ isActive }">
<span :class="{ active: isActive }">About</span>
</template>
</Link>
Outlet
Renders the matched child route component.
Navigate
Declarative redirect (triggers navigation in onMounted).
Await
Async setup component for deferred data — use with Vue's <Suspense>.
CatchBoundary
Error boundary using Vue's onErrorCaptured.
Html and Body
Vue-specific SSR shell components:
function RootComponent() {
return (
<Html>
<head>
<HeadContent />
</head>
<Body>
<Outlet />
<Scripts />
</Body>
</Html>
)
}
ClientOnly
Renders children only after onMounted (hydration complete):
<ClientOnly fallback={<div>Loading...</div>}>
<BrowserOnlyWidget />
</ClientOnly>
Vue-Specific Patterns
Custom Link Component with createLink
import { createLink } from '@tanstack/vue-router'
import { defineComponent, h } from 'vue'
const StyledLinkComponent = defineComponent({
setup(props, { slots, attrs }) {
return () => h('a', { ...attrs, class: 'styled-link' }, slots.default?.())
},
})
const StyledLink = createLink(StyledLinkComponent)
Render Functions (h())
All components in @tanstack/vue-router use h() render functions internally. Route components can use either SFC templates or render functions:
SFC template (most common for user code) in MyRoute.component.vue:
<template>
<div>{{ data.title }}</div>
</template>
<script setup>
import { useLoaderData } from '@tanstack/vue-router'
const data = useLoaderData({ from: '/posts/$postId' })
</script>
Auth with Router Context
import { createRootRouteWithContext } from '@tanstack/vue-router'
const rootRoute = createRootRouteWithContext<{ auth: AuthState }>()({
component: RootComponent,
})
const router = createRouter({
routeTree,
context: { auth: authState },
})
// In a route — access via beforeLoad
beforeLoad: ({ context }) => {
if (!context.auth.isAuthenticated) {
throw redirect({ to: '/login' })
}
}
Vue File Conventions for Code Splitting
With autoCodeSplitting, Vue routes can optionally use split-file conventions. These are NOT required — single-file .tsx routes work fine. Split files are useful for separating route config from components:
myRoute.ts— route configuration (search params, loader, beforeLoad)myRoute.component.vue— route component (lazy-loaded)myRoute.errorComponent.vue— error component (lazy-loaded)myRoute.notFoundComponent.vue— not-found component (lazy-loaded)myRoute.lazy.ts— lazy-loaded route options
Common Mistakes
1. CRITICAL: Forgetting .value in script blocks
Composables return Ref<T> — access via .value in <script>. Templates auto-unwrap.
// WRONG — accessing Ref without .value in script
const params = useParams({ from: '/posts/$postId' })
console.log(params.postId) // undefined!
// CORRECT — use .value
const params = useParams({ from: '/posts/$postId' })
console.log(params.value.postId)
2. HIGH: Confusing with vue-router (official)
@tanstack/vue-router is NOT vue-router. Do not use <router-view>, <router-link>, useRoute(), useRouter() from vue-router.
// WRONG — official vue-router imports
import { useRoute, useRouter } from 'vue-router'
// CORRECT — TanStack Vue Router imports
import { useMatch, useRouter } from '@tanstack/vue-router'
3. HIGH: Using Vue hooks in beforeLoad or loader
beforeLoad and loader are NOT component setup functions — they are plain async functions. Vue composables cannot be used in them. Pass state via router context instead.
4. MEDIUM: Wrong plugin target
Must set target: 'vue' in the router plugin config. Default is 'react'.
Cross-References
@tanstack/router-core#router-core— all sub-skills for domain-specific patterns (search params, data loading, navigation, auth, SSR, etc.)
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/tanstack/router/vue-router">View vue-router on skillZs</a>