1# Nuxt File-Based Routing
2 
3## When to Use
4 
5Working with `pages/` or `layouts/` directories, file-based routing, navigation.
6 
7## File-Based Routing Basics
8 
9`pages/` folder structure directly maps to routes. File names determine URLs.
10 
11## Naming Conventions
12 
13**Key principles:**
14 
15- **ALWAYS use descriptive params:** `[userId].vue` NOT `[id].vue`
16- **Optional params:** `[[paramName]].vue`
17- **Catch-all:** `[...path].vue`
18- **Route groups for organization:** `(folder)/` groups files without affecting URLs
19 
20## Red Flags - Stop and Check Skill
21 
22If you're thinking any of these, STOP and re-read this skill:
23 
24- "String paths are simpler than typed routes"
25- "Generic param names like [id] are fine"
26- "I remember how Nuxt 3 worked"
27 
28All of these mean: You're about to use outdated patterns. Use Nuxt 4 patterns instead.
29 
30## File Structure Example
31 
32```
33pages/
34├── index.vue               # /
35├── about.vue               # /about
36├── [...slug].vue           # catch-all for 404
37├── users.vue               # parent route (layout for /users/*)
38└── users/
39    ├── index.vue           # /users
40    └── [userId].vue        # /users/:userId
41```
42 
43## Route Groups for Organization
44 
45Route groups organize files WITHOUT affecting URLs. Wrap folder names in parentheses:
46 
47```
48pages/
49├── (marketing)/            # group folder (ignored in URL)
50│   ├── about.vue           # /about (not /marketing/about)
51│   └── pricing.vue         # /pricing
52└── (admin)/                # group folder (ignored in URL)
53    ├── dashboard.vue       # /dashboard
54    └── settings.vue        # /settings
55```
56 
57**Use route groups to:**
58 
59- Organize pages by feature/team
60- Group related routes without affecting URLs
61- Keep large projects maintainable
62- Apply middleware to specific groups (via `route.meta.groups`)
63 
64**Access route groups in middleware:**
65 
66```ts
67// middleware/auth.global.ts
68export default defineNuxtRouteMiddleware((to) => {
69  // Check if route is in admin group
70  if (to.meta.groups?.includes('admin')) {
71    const auth = useAuthStore()
72    if (!auth.isAdmin) return navigateTo('/')
73  }
74})
75```
76 
77## Parent Routes (Layouts)
78 
79Parent route = layout for nested routes:
80 
81```vue
82<!-- pages/users.vue -->
83<template>
84  <div class="users-layout">
85    <nav>
86      <NuxtLink to="/users">All Users</NuxtLink>
87      <NuxtLink to="/users/create">Create User</NuxtLink>
88    </nav>
89    <NuxtPage />
90  </div>
91</template>
92```
93 
94Child routes:
95 
96```
97pages/
98├── users.vue           # Parent route with <NuxtPage />
99└── users/
100    ├── index.vue       # /users
101    ├── [userId].vue    # /users/:userId
102    └── create.vue      # /users/create
103```
104 
105## definePage() for Route Customization
106 
107```vue
108<script setup lang="ts">
109definePage({
110  name: 'user-profile',
111  path: '/profile/:userId',  // Override default path
112  alias: ['/me', '/profile'],
113  meta: {
114    requiresAuth: true,
115    title: 'User Profile',
116    roles: ['user', 'admin']
117  }
118})
119</script>
120 
121<template>
122  <div>Profile content</div>
123</template>
124```
125 
126## Typed Router
127 
128**ALWAYS use typed routes for navigation:**
129 
130```ts
131// ✅ Type-safe with route name
132await navigateTo({ name: '/users/[userId]', params: { userId: '123' } })
133 
134// ❌ String-based (not type-safe, avoid)
135await navigateTo('/users/123')
136```
137 
138**REQUIRED: Check `typed-router.d.ts` for available route names and params before navigating.**
139 
140## useRoute with Types
141 
142Pass route name for stricter typing:
143 
144```ts
145// Generic route
146const route = useRoute()
147 
148// Typed route (preferred)
149const route = useRoute('/users/[userId]')
150// route.params.userId is now typed correctly
151```
152 
153## Navigation
154 
155```ts
156// Navigate to route
157await navigateTo('/about')
158await navigateTo({ name: '/users/[userId]', params: { userId: '123' } })
159 
160// Navigate with query
161await navigateTo({ path: '/search', query: { q: 'nuxt' } })
162 
163// External redirect
164await navigateTo('https://nuxt.com', { external: true })
165 
166// Replace history
167await navigateTo('/login', { replace: true })
168 
169// Open in new tab
170await navigateTo('/docs', { open: { target: '_blank' } })
171```
172 
173## Route Meta & Middleware
174 
175```vue
176<script setup lang="ts">
177definePageMeta({
178  middleware: ['auth', 'admin'],
179  layout: 'dashboard',
180  meta: {
181    requiresAuth: true
182  }
183})
184</script>
185```
186 
187## Dynamic Layout Switching
188 
189Use `setPageLayout()` to switch layouts programmatically:
190 
191```vue
192<script setup lang="ts">
193const user = useUser()
194 
195// Switch layout based on auth state
196if (!user.value) {
197  setPageLayout('guest')
198} else {
199  setPageLayout('dashboard')
200}
201 
202// With layout props (Nuxt 4.3+)
203setPageLayout('dashboard', {
204  sidebar: 'collapsed',
205  theme: 'dark'
206})
207</script>
208```
209 
210## Dynamic Routes Patterns
211 
212```
213[userId].vue              # /users/123
214[[slug]].vue              # /blog or /blog/post (optional)
215[...path].vue             # /a/b/c (catch-all)
216[[...path]].vue           # / or /a/b/c (optional catch-all)
217```
218 
219## Best Practices
220 
221- **`index.vue` for index routes** - valid and correct for creating default routes
222- **Route groups `(folder)/` for organization** - group files without affecting URLs
223- **Descriptive param names** - `[userId]` not `[id]`, `[postSlug]` not `[slug]`
224- **Type-safe navigation** - use route names, not strings
225- **Check typed-router.d.ts** for available routes
226- **Parent routes for layouts** - `users.vue` with `<NuxtPage />`
227- **Use definePage** for custom paths/aliases
228- **Catch-all for 404** - `[...path].vue` or `[...slug].vue`
229 
230## Common Mistakes
231 
232| ❌ Wrong                     | ✅ Right                                                          |
233| ---------------------------- | ----------------------------------------------------------------- |
234| `[id].vue`                   | `[userId].vue` or `[postId].vue`                                  |
235| `navigateTo('/users/' + id)` | `navigateTo({ name: '/users/[userId]', params: { userId: id } })` |
236| `<Nuxt />`                   | `<NuxtPage />`                                                    |
237| Separate layouts/ folder     | Parent routes with `<NuxtPage />`                                 |
238 
239## Resources
240 
241- Nuxt routing: https://nuxt.com/docs/guide/directory-structure/pages
242- File-based routing: https://nuxt.com/docs/getting-started/routing
243