Nuxt

name: routing description: File-based routing, dynamic routes, navigation, and middleware in Nuxt

Routing

Nuxt uses file-system routing based on vue-router. Files in app/pages/ automatically create routes.

Nuxt 5 Routing Defaults

• Case-sensitive matching (router.options.sensitive: true) — /About no longer matches pages/about.vue. Match link casing to file names, or set router: { options: { sensitive: false } }. sensitive can only be set in nuxt.config (the build fails if app/router.options.ts sets it). With sensitive: false, route rules match lower-cased paths, so regex constraints in rule patterns must be written for lower-case ([a-z], not [A-Z]).

• Typed pages on by default (experimental.typedPages) — useRoute, navigateTo, <NuxtLink :to>, and router.push are type-checked against your real routes. Referencing a route that doesn't exist is a type error. Opt out with experimental.typedPages: false.

• Normalized page component names — a page is named after its route, not its filename (pages/foo/index.vue → foo, not index). Update any <KeepAlive :include> filters to route names, or set experimental.normalizePageNames: false.

• Serializable page meta extracted at build time — every JSON-serializable definePageMeta() property is written into the generated route record; only non-serializable values (functions, refs, spreads) resolve at runtime.

• Route rule patterns use URLPattern - '/blog/*' now matches nested paths (/blog/2026/hello); use '/blog/:slug' for one segment. Only one */** per key (use /:post/comments/**). Regex constraints cannot match % or percent-encoded chars, or use \b. Rules also support proxy: 'https://api.example.com/**'.

• Unmatched client navigations load as a full document (experimental.serverPathFallback) so <NuxtLink to="/file.pdf"> reaches public/ files or server routes.

• Build-time link check - experimental.templateDiagnostics warns (NUXT_B4025) when a static <NuxtLink to> matches no page route.

Basic Routing

pages/
├── index.vue      → /
├── about.vue      → /about
└── posts/
    ├── index.vue  → /posts
    └── [id].vue   → /posts/:id

Dynamic Routes

Use brackets for dynamic segments:

pages/
├── users/
│   └── [id].vue       → /users/:id
├── posts/
│   └── [...slug].vue  → /posts/* (catch-all)
└── [[optional]].vue   → /:optional? (optional param)

Access route parameters:

<script setup lang="ts">
const route = useRoute()
// /posts/123 → route.params.id = '123'
console.log(route.params.id)
</script>

Navigation

NuxtLink Component

<template>
  <nav>
    <NuxtLink to="/">Home</NuxtLink>
    <NuxtLink to="/about">About</NuxtLink>
    <NuxtLink :to="{ name: 'posts-id', params: { id: 1 } }">Post 1</NuxtLink>
  </nav>
</template>

NuxtLink automatically prefetches linked pages when they enter the viewport.

Programmatic Navigation

<script setup lang="ts">
const router = useRouter()

function goToPost(id: number) {
  navigateTo(`/posts/${id}`)
  // or
  router.push({ name: 'posts-id', params: { id } })
}
</script>

Route Middleware

Named Middleware

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const isAuthenticated = false // Your auth logic

  if (!isAuthenticated) {
    return navigateTo('/login')
  }
})

Apply to pages:

<script setup lang="ts">
definePageMeta({
  middleware: 'auth',
  // or multiple: middleware: ['auth', 'admin']
})
</script>

Global Middleware

Name files with .global suffix:

// middleware/logging.global.ts
export default defineNuxtRouteMiddleware((to, from) => {
  console.log('Navigating to:', to.path)
})

Inline Middleware

<script setup lang="ts">
definePageMeta({
  middleware: [
    function (to, from) {
      // Inline middleware logic
    },
  ],
})
</script>

Page Meta

Configure page-level options:

<script setup lang="ts">
definePageMeta({
  title: 'My Page',
  layout: 'custom',
  middleware: 'auth',
  validate: (route) => {
    // Return false for 404, or object with status/statusText
    return /^\d+$/.test(route.params.id as string)
  },
})
</script>

Route Validation

<script setup lang="ts">
definePageMeta({
  validate: (route) => {
    // Must return boolean or object with status
    return typeof route.params.id === 'string' && /^\d+$/.test(route.params.id)
  },
})
</script>

Layouts

Define layouts in app/layouts/:

<!-- layouts/default.vue -->
<template>
  <div>
    <header>Header</header>
    <slot />
    <footer>Footer</footer>
  </div>
</template>

<!-- layouts/admin.vue -->
<template>
  <div class="admin">
    <AdminSidebar />
    <main>
      <slot />
    </main>
  </div>
</template>

Use in pages:

<script setup lang="ts">
definePageMeta({
  layout: 'admin',
})
</script>

Dynamic layout:

<script setup lang="ts">
const layout = ref('default')

function enableAdmin() {
  setPageLayout('admin')
}
</script>

Passing Props to Layouts (Nuxt 4.4+)

Use the object syntax for layout to pass typed props to the layout component:

<!-- app/pages/dashboard.vue -->
<script setup lang="ts">
definePageMeta({
  layout: { name: 'panel', props: { sidebar: true, title: 'Dashboard' } },
})
</script>

<!-- app/layouts/panel.vue -->
<script setup lang="ts">
const props = defineProps<{ sidebar?: boolean, title?: string }>()
</script>

Props are fully typed from the layout's defineProps. Also works dynamically: setPageLayout('panel', { sidebar: true }).

Named Views

A route can render into multiple <NuxtPage> outlets. Add named view files with the [email protected] convention next to the default route file:

pages/
├── parent.vue
└── parent/
    ├── child.vue           → default <NuxtPage />
    └── [email protected]   → <NuxtPage name="sidebar" />

<!-- pages/parent.vue -->
<template>
  <NuxtPage />
  <aside><NuxtPage name="sidebar" /></aside>
</template>

definePageMeta is read from the default route file only.

Navigation Hooks

<script setup lang="ts">
onBeforeRouteLeave((to, from) => {
  // Confirm before leaving
  const answer = window.confirm('Leave?')
  if (!answer) return false
})

onBeforeRouteUpdate((to, from) => {
  // Called when route changes but component is reused
})
</script>

<!-- Source references: - https://nuxt.com/docs/getting-started/routing - https://nuxt.com/docs/directory-structure/app/pages - https://nuxt.com/docs/directory-structure/app/middleware - https://nuxt.com/docs/api/utils/define-page-meta - https://nuxt.com/docs/getting-started/upgrade - https://nuxt.com/docs/guide/recipes/custom-routing - https://nuxt.com/docs/guide/concepts/rendering -->