1# Vue Router Typing
2 
3Type-safe routing patterns for Vue Router.
4 
5> **For Nuxt:** Use file-based routing instead. See `nuxt` skill for Nuxt routing patterns.
6 
7## Route Meta Types
8 
9Extend `RouteMeta` for typed route.meta:
10 
11```ts
12// router/types.ts
13import 'vue-router'
14 
15declare module 'vue-router' {
16  interface RouteMeta {
17    requiresAuth?: boolean
18    title?: string
19    roles?: ('admin' | 'user')[]
20  }
21}
22```
23 
24**Usage:**
25 
26```ts
27const route = useRoute()
28route.meta.requiresAuth // boolean | undefined (typed!)
29route.meta.title // string | undefined
30```
31 
32## Typed Route Params with unplugin-vue-router
33 
34Use `unplugin-vue-router` for fully typed routes:
35 
36```bash
37pnpm add -D unplugin-vue-router
38```
39 
40```ts
41// vite.config.ts
42import VueRouter from 'unplugin-vue-router/vite'
43 
44export default defineConfig({
45  plugins: [VueRouter(), Vue()], // VueRouter BEFORE Vue
46})
47```
48 
49**Typed useRoute:**
50 
51```ts
52// Auto-generated route types from file structure
53const route = useRoute('/users/[id]')
54route.params.id // string (typed!)
55 
56const route = useRoute('/posts/[...slug]')
57route.params.slug // string[] (typed!)
58```
59 
60**Typed router.push:**
61 
62```ts
63const router = useRouter()
64 
65// ✅ Type-checked
66router.push({ name: '/users/[id]', params: { id: '123' } })
67 
68// ❌ TypeScript error - wrong param
69router.push({ name: '/users/[id]', params: { userId: '123' } })
70```
71 
72## Scroll Behavior Types
73 
74Type scroll behavior function:
75 
76```ts
77import type { RouterScrollBehavior } from 'vue-router'
78 
79const scrollBehavior: RouterScrollBehavior = (to, from, savedPosition) => {
80  if (savedPosition) return savedPosition
81  if (to.hash) return { el: to.hash, behavior: 'smooth' }
82  return { top: 0 }
83}
84 
85const router = createRouter({
86  history: createWebHistory(),
87  routes,
88  scrollBehavior,
89})
90```
91 
92## Dynamic Route Params
93 
94Handle union types for dynamic segments:
95 
96```ts
97// routes/[type].vue where type can be 'posts' | 'users' | 'comments'
98const route = useRoute()
99 
100// Narrow params type
101type ContentType = 'posts' | 'users' | 'comments'
102 
103const type = route.params.type as ContentType
104 
105// Or use route guards
106if (route.params.type === 'posts') {
107  // TypeScript knows type is 'posts'
108}
109```
110 
111## Navigation Guards Types
112 
113Type navigation guards:
114 
115```ts
116import type { NavigationGuardWithThis, RouteLocationNormalized } from 'vue-router'
117 
118const authGuard: NavigationGuardWithThis<undefined> = (to, from) => {
119  if (to.meta.requiresAuth && !isAuthenticated()) {
120    return { name: 'login', query: { redirect: to.fullPath } }
121  }
122}
123 
124router.beforeEach(authGuard)
125```
126 
127**Per-route guards:**
128 
129```ts
130const routes = [
131  {
132    path: '/admin',
133    component: AdminPage,
134    beforeEnter: (to: RouteLocationNormalized) => {
135      if (!hasAdminRole()) return { name: 'forbidden' }
136    },
137  },
138]
139```
140 
141## RouteLocation Types
142 
143Common route types:
144 
145```ts
146import type {
147  RouteLocationNormalized,     // Resolved route (after navigation)
148  RouteLocationNormalizedLoaded, // Current route (from useRoute)
149  RouteLocationRaw,            // Input to router.push()
150  RouteRecordRaw,              // Route config definition
151} from 'vue-router'
152```
153 
154## Common Mistakes
155 
156**Not extending RouteMeta module:**
157 
158```ts
159// ❌ Loses type info
160route.meta.customField // any
161 
162// ✅ Extend the interface
163declare module 'vue-router' {
164  interface RouteMeta { customField: string }
165}
166```
167 
168**Assuming params are always strings:**
169 
170```ts
171// Catch-all routes have string[] params
172const route = useRoute()
173 
174// ❌ May be string[]
175const id = route.params.id
176 
177// ✅ Handle both cases
178const id = Array.isArray(route.params.id)
179  ? route.params.id[0]
180  : route.params.id
181```
182