---
url: /data-loaders/basic.md
---
# `defineBasicLoader()`

Basic data loader that always reruns on navigation.

::: warning
Data Loaders are experimental. Feedback is very welcome to shape the future of data loaders in Vue Router.
:::

## Setup

## Example

```vue
<script lang="ts">
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
import { getUserById } from '../api'

export const useUserData = defineBasicLoader(
  (to, { signal }) => {
    return getUserById(to.params.id, { signal })
  },
  {
    // used for SSR only
    key: 'user-data',
  }
)
</script>

<script lang="ts" setup>
const route = useRoute('/users/[id]')

const {
  user,
  error
  isLoading,
  reload,
} = useUserData()
</script>

<template>
  <main>
    <h1>Basic Data Loader Example</h1>
    <pre>User: {{ route.params.id }}</pre>

    <fieldset>
      <legend>Controls</legend>

      <button @click="reload()">Refetch</button>
    </fieldset>

    <RouterLink :to="{ params: { id: Number(route.params.id) || 0 - 1 } }"
      >Previous</RouterLink
    >
    |
    <RouterLink :to="{ params: { id: Number(route.params.id) || 0 + 1 } }"
      >Next</RouterLink
    >

    <h2>State</h2>

    <p>
      <code>isLoading: {{ isLoading }}</code>
    </p>
    <pre v-if="error">Error: {{ error }}</pre>
    <pre v-else>{{ user == null ? String(user) : user }}</pre>
  </main>
</template>
```

## SSR

## Nuxt

## Unresolved Questions

* Should this basic version also track what is used in the route object, like [Svelte Data Loaders do](https://kit.svelte.dev/docs/load#rerunning-load-functions)?

---

---
url: /data-loaders/colada.md
---
# `defineColadaLoader()`

Loaders that use [@pinia/colada](https://github.com/posva/pinia-colada) under the hood. These loaders provide a more efficient way to have asynchronous state with cache, ssr support and more.

The key used in these loaders are directly passed to `useQuery()` from `@pinia/colada` and are therefore invalidated by `useMutation()` calls.

::: warning
Pinia Colada is Experimental (like data loaders). Feedback is very welcome to shape the future of data loaders in Vue Router.
:::

## Setup

Follow the installation instructions in [@pinia/colada](https://github.com/posva/pinia-colada).

## Example

```vue
<script lang="ts">
import { defineColadaLoader } from 'unplugin-vue-router/data-loaders/pinia-colada'
import { getUserById } from '../api'

export const useUserData = defineColadaLoader({
  async query(to, { signal }) {
    return getUserById(to.params.id, { signal })
  },
  key: (to) => ['users', to.params.id],
  // Keep the data "fresh" 10 seconds to avoid fetching the same data too often
  staleTime: 10000,
})
</script>

<script lang="ts" setup>
const route = useRoute('/users/[id]')

const {
  user,
  status,
  error
  isLoading,
  reload,
  refresh,
} = useUserData()
</script>

<template>
  <main>
    <h1>Pinia Colada Loader Example</h1>
    <pre>User: {{ route.params.id }}</pre>

    <fieldset>
      <legend>Controls</legend>

      <button @click="refresh()">Refresh</button>
      <button @click="reload()">Refetch</button>
    </fieldset>

    <RouterLink :to="{ params: { id: Number(route.params.id) || 0 - 1 } }">
      Previous
    </RouterLink>
    |
    <RouterLink :to="{ params: { id: Number(route.params.id) || 0 + 1 } }">
      Next
    </RouterLink>

    <h2>State</h2>

    <p>
      <code>status: {{ status }}</code>
      <br />
      <code>isLoading: {{ isLoading }}</code>
    </p>
    <pre v-if="error">Error: {{ error }}</pre>
    <pre v-else>{{ user == null ? String(user) : user }}</pre>
  </main>
</template>
```

::: tip
If you are using unplugin-vue-router, you can pass a route name to `defineColadaLoader` to get typed routes in the `query` function.

```ts
export const useUserData = defineColadaLoader('/users/[id]', {
  // ...
})
```

:::

## Refresh by default

To avoid unnecessary frequent refreshes, Pinia Colada refreshes the data when navigating (instead of *refetching*). Change the `staleTime` option to control how often the data should be refreshed, e.g. setting it to 0 will refresh the data every time the route changes.

## Route tracking

The `query` function tracks what is used in the `to` parameter and will only refresh the data if **tracked** properties change. This means that if you use `to.params.id` in the `query` function, it will only refetch the data if the `id` parameter changes but not if other properties like `to.query`, `to.hash` or even `to.params.other` change. To make sure the data is updated, it will still refresh in these scenarios. Configure the `staleTime` option to control how often the data should be refreshed.

## SSR

<--!
Hydration does not trigger extra load
\-->

## Nuxt

## Unresolved questions

---

---
url: /data-loaders/apollo.md
---
# Apollo

WIP

---

---
url: /data-loaders/load-cancellation.md
---
# Cancelling a data loader

Data loaders receive an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can be passed to `fetch` and other Web APIs to cancel ongoing requests when the navigation is cancelled. If the navigation is cancelled because of errors or a new navigation, the signal aborts, causing any request using it to abort as well.

```ts twoslash
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchBookCollection(options: {
  signal?: AbortSignal
}): Promise<Book[]> {
  return {} as any
}
// ---cut---
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
export const useBookCollection = defineBasicLoader(
  async (_route, { signal }) => {
    return fetchBookCollection({ signal })
  }
)
```

This aligns with the future [Navigation API](https://github.com/WICG/navigation-api#navigation-monitoring-and-interception) and other web APIs that use the `AbortSignal` to cancel an ongoing invocation.

## Best practices

Depending on the data loader implementation, it might be more interesting **not** to cancel an ongoing request, for example, when using [Pinia Colada](./colada/), it might be more interesting to keep the request ongoing and cache the result for future navigations. Make sure to read the documentation

---

---
url: /guide/configuration.md
---
# Configuration

Have a glimpse of all the existing configuration options with their corresponding **default values**:

```ts twoslash
import type { TreeNode } from 'unplugin-vue-router/types'
const myOwnGenerateRouteName = (routeNode: TreeNode) => {
  return 'ok'
}
import { isPackageExists as isPackageInstalled } from 'local-pkg'
function getFileBasedRouteName(routeNode: TreeNode) {
  return 'ok'
}
// const process = { cwd: () => '' }
// ---cut---
// @moduleResolution: bundler
import VueRouter from 'unplugin-vue-router/vite'

VueRouter({
  // how and what folders to scan for files
  routesFolder: [
    {
      src: 'src/pages',
      path: '',
      // override globals
      exclude: (excluded) => excluded,
      filePatterns: (filePatterns) => filePatterns,
      extensions: (extensions) => extensions,
    },
  ],

  // what files should be considered as a pages
  extensions: ['.vue'],

  // what files to include
  filePatterns: ['**/*'],

  // files to exclude from the scan
  exclude: [],

  // where to generate the types
  dts: './typed-router.d.ts',

  // how to generate the route name
  getRouteName: (routeNode) => getFileBasedRouteName(routeNode),

  // default language for <route> custom blocks
  routeBlockLang: 'json5',

  // how to import routes, can also be a string
  importMode: 'async',

  // where are paths relative to
  root: process.cwd(),

  // options for the path parser
  pathParser: {
    // should `users.[id]` be parsed as `users/:id`?
    dotNesting: true,
  },

  // modify routes individually
  async extendRoute(route) {
    // ...
  },

  // modify routes before writing
  async beforeWriteFiles(rootRoute) {
    // ...
  },
})
```

::: tip
Highlight any of the options to see more details about it.
:::

## SSR

It might be necessary to mark `vue-router` as `noExternal` in your `vite.config.js` in development mode:

```ts{7}
import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import VueRouter from 'unplugin-vue-router/vite'

export default defineConfig(({ mode }) => ({
  ssr: {
    noExternal: mode === 'development' ? ['vue-router'] : [],
  },
  plugins: [VueRouter(), Vue()],
}))
```

---

---
url: /data-loaders.md
---
# Data Loaders

Data loaders streamline any asynchronous state management with Vue Router, like **Data Fetching**. Adopting Data loaders ensures a consistent and efficient way to manage data fetching in your application. Keep all the benefits of using libraries like [Pinia Colada](./colada/) or [Apollo](./apollo/) and integrate them seamlessly with client-side navigation.

This is achieved by extracting the loading logic **outside** of the component `setup` (unlike `<Suspense>`). This way, the loading logic can be executed independently of the component life cycle, and the component can focus on rendering the data. Data Loaders are automatically collected and awaited within a navigation guard, ensuring the data is ready before rendering the component.

## Features

* Parallel data fetching and deduplication
* Automatic loading state management
* Error handling
* Extensible by loader implementations
* SSR support
* Prefetching data support

## Installation

After installing [unplugin-vue-router](../introduction.md), install the `DataLoaderPlugin` **before the `router`**.

```ts{12-15} twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
// @moduleResolution: bundler
// ---cut---
import { createApp } from 'vue'
import { routes } from 'vue-router/auto-routes'
import { createRouter, createWebHistory } from 'vue-router'
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders' // [!code ++]

const router = createRouter({
  history: createWebHistory(),
  routes,
})

const app = createApp({})
// Register the plugin before the router
app.use(DataLoaderPlugin, { router }) // [!code ++]
// adding the router will trigger the initial navigation
app.use(router)
app.mount('#app')
```

## Quick start

There are different data loaders implementation, the most simple one is the [Basic Loader](./basic/) which always reruns data fetching. A more efficient one, is the [Colada Loader](./colada/) which uses [@pinia/colada](https://github.com/posva/pinia-colada) under the hood. In the following examples, we will be using the *basic loader*.

Loaders are [composables](https://vuejs.org/guide/reusability/composables.html) defined through a `defineLoader` function like `defineBasicLoader` or `defineColadaLoader`. They are *used* in the component `setup` to extract the needed information.

To get started, *define* and ***export*** a loader from a **page** component:

::: code-group

```vue{2,5-7,11-16} twoslash [src/pages/users/[id].vue]
<script lang="ts">
import 'unplugin-vue-router/client'
import './typed-router.d'
// ---cut---
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
import { getUserById } from '../api'

export const useUserData = defineBasicLoader('/users/[id]', async (route) => {
  return getUserById(route.params.id)
})
</script>

<script setup lang="ts">
const {
  data: user, // the data returned by the loader
  isLoading, // a boolean indicating if the loader is fetching data
  error, // an error object if the loader failed
  reload, // a function to refetch the data without navigating
} = useUserData()
</script>

<template>
  <main>
    <p v-if="isLoading">Loading...</p>
    <template v-else-if="error">
      <p>{{ error.message }}</p>
      <button @click="reload()">Retry</button>
    </template>
    <template v-else>
      <p>{{ user }}</p>
    </template>
  </main>
</template>
```

:::

The loader will automatically run when the route changes, for example when navigating to `/users/1`, even when coming from `/users/2`, the loader will fetch the data and delay the navigation until the data is ready.

On top of that, you are free to *reuse* the returned composable `useUserData` in any other component, and it will automatically share the same data fetching instance. You can even [organize your loaders in separate files](./organization.md) as long as you **export** the loader from a **page** component.

## Why Data Loaders?

Data fetching is the most common need for a web application. There are many ways of handling data fetching, and they all have their pros and cons. Data loaders are a way to streamline data fetching in your application. Instead of forcing you to choose between different libraries, data loaders provide a consistent way to manage data fetching in your application no matter the underlying library or strategy you use.

---

---
url: /data-loaders/rfc.md
---

# Data Loaders

* Start Date: 2022-07-14
* Target Major Version: Vue 3, Vue Router 4
* Reference Issues: -
* [Discussion](https://github.com/vuejs/rfcs/discussions/460)
* [Implementation PR](https://github.com/posva/unplugin-vue-router/tree/main/src/data-loaders)

## Todo List

List of things that haven't been added to the document yet:

* \[ ] Extendable API for data fetching libraries like vue-apollo, vuefire, vue-query, etc
* \[ ] Warn if a non lazy loader is used without data: meaning it was used in a component without it being exported by a page component. Either make it lazy or export it

## Summary

There is no silver bullet to data fetching because of the different data fetching strategies and how they can define the architecture of the application and its UX. However, I think it's possible to find a solution that is flexible enough to **promote good practices** and **reduce the complexity** of data fetching in applications.
That is the goal of this RFC, to standardize and improve data fetching with vue-router:

* Integrate data fetching to the navigation cycle
  * Blocks navigation while fetching or *defer* less important data (known as *lazy* in Nuxt)
* Deduplicate requests
* Delay data updates until all data loaders are resolved
  * Avoids displaying partially up-to-date data and inconsistent state
  * Configurable through a `commit` option
* Optimal data fetching
  * Defaults to parallel fetching
  * Semantic sequential fetching if needed
* Avoid `<Suspense>`
  * No cascading loading states
  * No double mounting
  * [more...](#suspense)
* Provide atomic and global access to loading/error states
* Allow 3rd party libraries to extend the loaders functionality by establish a set of Interfaces that can be implemented. This targets libraries like [VueFire](https://vuefire.vuejs.org), [@pinia/colada][pinia-colada], [vue-apollo](https://apollo.vuejs.org/), [@tanstack/vue-query][vue-query], etc to provide features like caching, pagination, etc. specific to their use cases.

This proposal concerns Vue Router 4 and is implemented under [unplugin-vue-router][uvr]. This enables types in data loaders but **is not necessary**. This feature is independent of the rest of the plugin and can be used without it, namely **without file-based routing**.

::: tip
In this RFC, data loaders are often referred as *loaders* for short. API names also use the word *loader* instead of *data loader* for brevity.

💡 Some of the examples are interactive: hover or tap on the code to see the types and other information.
:::

## Basic example

We create data loaders with a `defineLoader()` function that returns a **composable that can be used in any component** (not only pages component).

The loader is then picked up by a Navigation Guard. It can be attached to a page component in two ways:

* Export the loader from the page component it is attached to. It must be lazy loaded (`() => import('~/pages/users-details.vue')`)
* Manually add the loader to the route definition's `meta.loaders[]`

Exported from a non-setup `<script>` in a page component:

```vue twoslash
<script lang="ts">
// ---cut-start---
import { defineComponent } from 'vue'
import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
// ---cut-end---
// @moduleResolution: bundler
import { getUserById } from '../api'

// name the loader however you want **and export it**
export const useUserData = defineLoader(async (route) => {
  const user = await getUserById(route.params.id as string)
  // ...
  // return anything you want to expose
  return user
})

// Optional: define other component options
export default defineComponent({
  name: 'custom-name',
  inheritAttrs: false,
})
</script>

<script lang="ts" setup>
// find the user as `data` and some other properties
const { data: user, isLoading, error, reload } = useUserData()
// data is always present, isLoading changes when going from '/users/2' to '/users/3'
</script>
```

When a loader is exported by the page component, it is **automatically** picked up as long as the route is **lazy loaded** (which is a best practice). If the route isn't lazy loaded, the loader can be directly defined in an array of data loaders on `meta.loaders`:

```ts twoslash
import './shims-vue.d'
// ---cut---
// @moduleResolution: bundler
import { createRouter, createWebHistory } from 'vue-router'
import UserList from './pages/UserList.vue'
// could be anywhere
import { useUserList, useUserData, type User } from './loaders/users'

export const router = createRouter({
  history: createWebHistory(),
  routes: [
    {
      path: '/users',
      component: UserList,
      meta: {
        // Required when the component is not lazy loaded
        loaders: [useUserList],
      },
    },
    {
      path: '/users/:id',
      // automatically picks up all exported loaders
      component: () => import('./pages/UserDetails.vue'),
    },
  ],
})
```

Regarding the returned values from `useUserData()`:

* `data` (aliased to `user`), `isLoading`, and `error` are shallow ref and therefore reactive.
* `reload` is a function that can be called to force a reload of the data without a new navigation.

Note `useUserData()` can be used in **any component**, not only in the page component: just import the function and call it within `<script setup>` like other composables

By default, **data loaders block the navigation**, meaning they *just work* with SSR and errors are propagated to the router level (`router.onError()`). On top of that, data loads are deduplicated, which means that no mather how many page components use the same loader (e.g. nested pages), **it will still load the data just once per navigation**.

The simplest of data loaders can be defined in just one line and types will be automatically inferred:

```ts twoslash
import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchBookCollection(): Promise<Book[]> {
  return {} as any
}
// ---cut---
export const useBookCollection = defineLoader(fetchBookCollection)
const { data } = useBookCollection()
```

Note that this syntax will intentionally be avoided in the RFC. Instead, we will often use slightly longer examples to make things easier to follow.

## Motivation

There are currently too many ways of handling data fetching with vue-router and all of them have problems:

* With navigation guards:
  * using `onBeforeRouteUpdate()`: only works on subsequent navigations. Cannot be properly combined with `beforeRouteEnter()`.
  * using `beforeRouteEnter()`: non typed and non-ergonomic API with `next()`, requires a data store (pinia, vuex, apollo, etc), does not exist in script setup
  * using `meta`: complex to setup even for simple cases, too low level for such a common case
* using a watcher on `route.params...`: component renders without the data (doesn't work with SSR)
* Using Suspense and *awaiting* data within page components
  * Cascading (slow) async states
  * Only loads once (on mounting)
  * Does not wait for navigation (or requires double mounting: pending + current view)
  * Requires handling UI loading state
  * [And more](#suspense)

People are left with a low level API (navigation guards) to handle data fetching themselves. This is often a difficult problem to solve because it requires an extensive knowledge of the Router concepts and in reality, very few people know them. This leads to incomplete implementations that don't handle all the edge cases and don't provide a good user experience.

Thus, the goal of this proposal is to provide a simple yet extendable way of defining data loading in your application that is easy to understand and use. It should also be compatible with SSR and not limited to simple *fetch calls*, but rather any async state. It should be adoptable by frameworks like Nuxt.js to provide an augmented data fetching layer that integrates well with Vue.js concepts and the future of Web APIs like the [Navigation API](https://github.com/WICG/navigation-api/).

## Detailed design

The design of Data Loaders is split into two parts

* [Implementations](#implementations)
  * A bare-bone data loader
  * A more advanced data loader with client side caching using [@pinia/colada][pinia-colada]
* The set of [Interfaces (types)](#interfaces) that define a Data Loader (WIP)

::: tip
You might only be interested in trying out Data Loaders. In that case, check out the [implementations](#implementations) section for instructions on how to use this. It's still recommended to read the rest of the RFC to understand what to expect from Data Loaders.
:::

### Data Loader Setup

`DataLoaderPlugin` adds the [navigation guard](#the-navigation-guard) that handles the data loaders. It requires access to the router instance to attach the navigation guard as well as some other options:

* `router`: The Vue Router instance.
* `selectNavigationResult` (optional): Called wih an array of `NavigationResult` returned by loaders. It allows to decide the *fate* of the navigation that was modified by loaders. See [NavigationResult](#handling-multiple-navigation-results)

```ts{2,9}
import { createApp } from 'vue'
import { createRouter } from 'vue-router'
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders'

const router = createRouter({
  // ...
})

const app = createApp(App)
app.use(DataLoaderPlugin, { router })
// add the router after the DataLoaderPlugin
app.use(router)
```

It's important to add the `DataLoaderPlugin` before the router to ensure the navigation guards are attached before the router initiates the first navigation.

### Core Data Loader features

These are the core features of the Data Loader API that every data loader should implement. Throughout the RFC, we will use a **non-existent**, **generic** `defineLoader()`. This is a placeholder for the actual name of the function, e.g. [`defineBasicLoader()`](./basic/), [`defineColadaLoader()`](./colada/), etc. In practice, one can globally alias the function to `defineLoader` with [unplugin-auto-import](https://github.com/unplugin/unplugin-auto-import).

Data Loaders should be able to load data based **solely on the URL**. This ensures that the page can be shared and that the rendering is consistent between the server and the client.

#### `defineLoader()` signature

Data Loaders must accept an optional first parameter to type the route:

```ts twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
// ---cut---
import { getUserById } from '../api'

export const useUserData = defineLoader('/users/[id]', async (route) => {
  return getUserById(route.params.id)
})
```

The rest of the parameters are up to the implementation of the loader but they should accept [extra options](#defineloader-options).

Within loaders there is no access to the current component or page instance, but it's possible to access global injections created with `app.provide()`. This includes stores created with [Pinia](https://pinia.vuejs.org).

#### Returned Composables

Data Loaders are composables that return a set of properties:

```ts twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { useUserData } from './loaders/users'
// ---cut---
const {
  // hover over each property to see the type
  data,
  isLoading,
  error,
  reload,
} = useUserData()
```

* `data` contains the resolved value returned by the loader. It's a shallow ref to be more performant, especially with large data-sets
* `isLoading` is `true` while a request is isLoading and becomes `false` once the request is settled
* `error` contains any error thrown by the loader. It's also a shallow ref
* `reload()` reruns the loader outside of a navigation

In practice, rename `data` (or others) to something more meaningful:

```ts twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { useUserData } from './loaders/users'
// ---cut---
const { data: user } = useUserData()
```

#### `defineLoader()` options

* `lazy`: By default, loaders block the navigation. This means that the navigation is only allowed to continue once all loaders are resolved. Lazy loaders **do not block the navigation**. `data`, `error` and other properties might be updated after the navigation finishes. Setting this to `true` is useful for non-critical data fetching and will change the type of the returned `data` to `ShallowRef<T | undefined>`:

  ```ts twoslash
  import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
  interface Book {
    title: string
    isbn: string
    description: string
  }
  function fetchBookCollection(): Promise<Book[]> {
    return {} as any
  }
  // ---cut---
  export const useBookCollection = defineLoader(fetchBookCollection, {
    lazy: true,
  })
  const { data: bookCollection } = useBookCollection()
  //            ^ can be undefined
  ```

* `commit`: Controls when the async state is reflected in `data` and `error`. You can choose to immediately reflect the state of the loader or
  delay the update of the data until all loaders are resolved (default). The latter is useful to avoid displaying partially up-to-date data and inconsistent state.

  ```ts twoslash
  import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
  interface Book {
    title: string
    isbn: string
    description: string
  }
  function fetchBookCollection(): Promise<Book[]> {
    return {} as any
  }
  // ---cut---
  export const useBookCollection = defineLoader(fetchBookCollection, {
    commit: 'immediate',
  })
  ```

  A lazy loader can use `commit: 'after-load'` but since it's not awaited during the navigation, it might be reflected **after the navigation**.

* `server`: By default, loaders are executed on both, client, and server. Setting this to false will skip its execution on the server. Like `lazy: true`, this also changes the type of the returned `data` to `ShallowRef<T | undefined>`:

  ```ts twoslash
  import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
  interface Book {
    title: string
    isbn: string
    description: string
  }
  function fetchBookCollection(): Promise<Book[]> {
    return {} as any
  }
  // ---cut---
  export const useBookCollection = defineLoader(fetchBookCollection, {
    server: false,
  })
  ```

Each custom implementation can augment the returned properties with more information. For example, [Pinia Colada](./colada/) adds `refresh()`, `status` and other properties specific to its features.

#### Parallel Fetching

By default, loaders are executed as soon as possible, in parallel. This scenario works well for most use cases where data fetching only requires route params/query params or nothing at all.

#### Sequential fetching

Sometimes, requests depend on other fetched data (e.g. fetching additional user information). For these scenarios, we can simply import the other loaders and use them **within a different loader**:

Call **and `await`** the loader inside the one that needs it, it will only be fetched once no matter how many times it is called during a navigation:

```ts twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
// ---cut---
// import the loader for user information
import { useUserData } from './loaders/users'
import { getCommonFriends, getCurrentUser } from './api'

export const useUserCommonFriends = defineLoader(async (route) => {
  // loaders must be awaited inside other loaders
  // .        ⤵
  const user = await useUserData() // magically works
  const me = await getCurrentUser()

  // fetch other data
  const commonFriends = await getCommonFriends(me.id, user.id)
  return { ...user, commonFriends }
})
```

You will notice here that we have two different usages for `useUserData()`:

* One that returns all the necessary information we need *synchronously* (not used here). This is the composable that we use in components
* A second version that **only returns a promise of the data**. This is the version used within data loaders that enables sequential fetching.

::: danger
`useUserData()` expects the route to have an `id` param to fetch the current user. We could maybe allow passing the route as a parameter to ensure the type safety as well to further differentiate the two usages (and their type).
:::

##### Nested invalidation

Since `useUserCommonFriends()` loader calls `useUserData()`, if `useUserData()` is somehow *invalidated*, it will also automatically invalidate `useUserCommonFriends()`. This depends on the implementation of the loader and is not a requirement of the API.

::: warning
Two loaders cannot use each other as that would create a *dead lock*.
:::

This can get complex with multiple pages exposing the same loader and other pages using some of their *already exported* loaders within other loaders. But it's not an issue, **the user shouldn't need to handle anything differently**, loaders are still only called once:

```ts twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
// ---cut---
import {
  getFriends,
  getCommonFriends,
  getUserById,
  getCurrentUser,
} from './api'

export const useUserData = defineLoader('/users/[id]', async (route) => {
  return getUserById(route.params.id)
})

export const useCurrentUserData = defineLoader('/users/[id]', async (route) => {
  const me = await getCurrentUser()
  // imagine legacy APIs that cannot be grouped into one single fetch
  const friends = await getFriends(me.id)

  return { ...me, friends }
})

export const useUserCommonFriends = defineLoader(
  '/users/[id]',
  async (route) => {
    const user = await useUserData()
    const me = await useCurrentUserData()

    const friends = await getCommonFriends(user.id, me.id)
    return { ...me, commonFriends: { with: user, friends } }
  }
)
```

In the example above we are exporting multiple loaders but we don't need to care about the order in which they are called nor try optimizing them because **they are only called once and share the data**.

::: danger
**Caveat**: must call **and await** all nested loaders at the top of the parent loader (see `useUserData()` and `useCurrentUserData()`). You cannot put a different regular `await` in between. If you really need to await **anything that isn't a loader** in between, wrap the promise with `withDataContext()` to ensure the loader context is properly restored:

```ts{3}
export const useUserCommonFriends = defineLoader(async (route) => {
  const user = await useUserData()
  await withContext(functionThatReturnsAPromise())
  const me = await useCurrentUserData()

  // ...
})
```

This allows nested loaders to be aware of their *parent loader*. This could probably be linted with an eslint plugin. It is similar to the problem `<script setup>` had before introducing the automatic `withAsyncContext()`. The same feature could be introduced (via a vite plugin) but will also have a performance cost. In the future, this *should* be solved with the [async-context](https://github.com/tc39/proposal-async-context) proposal (stage 2).
:::

#### Cache&#x20;

::: warning
This part has been removed from the core features of the API. It's now part of custom implementations like [Pinia Colada](./colada/).
:::

#### Smart Refreshing

This is not a requirement of the API.

When navigating, depending on the loader, the data is refreshed **automatically based on what params, query params, and hash** are used within the loader.

e.g. using [Pinia Colada](./colada/), given this loader in page `/users/:id`:

```ts
export const useUserData = defineColadaLoader(async (route) => {
  const user = await getUserById(route.params.id)
  return user
})
```

Going from `/users/1` to `/users/2` will reload the data but going from `/users/2` to `/users/2#projects` will not unless the cache expires or is manually invalidated (known as *refresh*).

#### Deduplication

Loaders also have the advantage of behaving as singleton requests. This means that they are only fetched once per navigation no matter how many times the loader is attached or how many regular components use it. It also means that all the refs (`data`, `isLoading`, etc) are created only once and shared by all components, reducing memory usage.

#### SSR

Each Data Loader implementation is responsible for providing a way to serialize the data loaded on the server and pass it to the client. This is a requirement for SSR to work properly.

Different implementations could have different kind of keys. The simplest form is a string:

```ts
export const useBookCollection = defineLoader(
  async () => {
    const books = await fetchBookCollection()
    return books
  },
  { key: 'bookCollection' }
)
```

##### Avoiding double fetch on the client

One of the advantages of having an initial state is that we can avoid fetching on the client. Data Loaders can implement a mechanism to skip fetching on the client if the initial state is provided ([Pinia Colada](./colada/) implements this). This means nested loaders **aren't executed either**. Since data loaders shouldn't contain side effects besides data fetching, this shouldn't be a problem.

### The Navigation Guard

The bulk of the logic of data loaders is handled with navigation guards:

* one `router.beforeEach()` to collect loaders from lazy loaded components
* one `router.beforeResolve()` (triggers after other guards) to execute the loaders

`router.afterEach()` and `router.onError()` are also used to handle errors and cleanup.

Handling the data loading in a navigation guards has the following advantages:

* Ensure data is present before mounting the component
* Flexibility to not wait for non critical data with lazy data loaders
* Enables the UX pattern of letting the browser handle loading state (aligns with [future Navigation API](https://github.com/WICG/navigation-api))
* Makes scrolling work out of the box when navigating between pages (when data loaders are blocking)
* Ensure one single request per loader and navigation
* Allows controlling the navigation (aborting, redirecting, etc)

#### Controlling the navigation

Since the data fetching happens within a navigation guard, it's possible to control the navigation like in regular navigation guards:

* Thrown errors (or rejected Promises) cancel the navigation (same behavior as in a regular navigation guard) and are intercepted by [Vue Router's error handling](https://router.vuejs.org/api/interfaces/router.html#onerror)
* Redirection: `return new NavigationResult(targetLocation)` -> like `return targetLocation` in a regular navigation guard
* Cancelling the navigation: `return new NavigationResult(false)` like `return false` in a regular navigation guard
* Any other returned value is considered as the *resolved data*

```ts{1,11,14}
import { NavigationResult } from 'vue-router'

export const useUserData = defineLoader(
  async (to) => {
    try {
      const user = await getUserById(to.params.id)

      return user
    } catch (error) {
      if (error.status === 404) {
        return new NavigationResult({ name: 'not-found', params: { pathMatch: '' } }
        )
      } else {
        throw error // aborts the vue router navigation
      }
    }
  }
)
```

`new NavigationResult()` accepts as its only argument anything that [can be returned in a navigation guard](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) to alter the navigation. e.g. it doesn't accept `true` or `undefined` as these do not modify the navigation.

Some alternatives:

::: details

* `createNavigationResult()`: too verbose
* `NavigationResult()` (no `new`): `NavigationResult` is not a primitive so it should use `new`
* Accept a second argument for extra custom context that can be retrieved in `selectNavigationResult()`

:::

::: tip

Throwing an error does not trigger the `selectNavigationResult()` method. Instead, it immediately cancels the navigation and triggers the `router.onError()` method, just like in a regular navigation guard.

:::

#### Handling multiple navigation results

Since navigation loaders can run in parallel, they can return different navigation results as well. In this case, you can decide which result should be used by providing a `selectNavigationResult()` method to [`DataLoaderPlugin`](#data-loader-setup):

```ts{3-6} twoslash
import 'unplugin-vue-router/client'
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders'
const app = createApp({})
const router = createRouter({
  history: createWebHistory(),
  routes: [],
})
// ---cut---
// @moduleResolution: bundler
// @noErrors
app.use(DataLoaderPlugin, {
  router,
  selectNavigationResult(results) {
    for (const { value } of results) {
      if (
        typeof value === 'object' &&
        'name' in value &&
        value.name === 'not-found'
      ) {
        return value
      }
    }
  },
})
```

`selectNavigationResult()` is called with an array of all the returned `new NavigationResult(value)` **after all data loaders** have been resolved. **If any of them throws an error** or if none of them return a `NavigationResult`, `selectNavigationResult()` isn't called.

By default, `selectNavigation` returns the first value of the array.

#### Eagerly changing the navigation

If a loader wants to eagerly alter the navigation, it can `throw` the `NavigationResult` instead of returning it. This skips the `selectNavigationResult()` and take precedence without triggering `router.onError()`.

```ts{10-15}
import { NavigationResult } from 'unplugin-vue-router/data-loaders'

export const useUserData = defineLoader(
  async (to) => {
    try {
      const user = await getUserById(to.params.id)

      return user
    } catch (error) {
      throw new NavigationResult({
        name: 'not-found',
        params: { pathMatch: to.path.split('/') },
        query: to.query,
        hash: to.hash,
      })
    }
  }
)
```

::: info

When using vue router named views, each named view can have their own loaders but note any navigation to the route will trigger **all loaders from all page components**. This is because the router doesn't know which named views will be used.

:::

### Advanced Error handling

Since throwing an error in a loader cancels the navigation, this doesn't allow to have an error property in *non lazy loaders* to display the error in the UI. To solve this, we can specify expected errors when defining the loader:

```ts{2-9,16}
// custom error class
class MyError extends Error {
  // override is only needed in TS
  override name = 'MyError' // Displays in logs instead of 'Error'
  // defining a constructor is optional
  constructor(message: string) {
    super(message)
  }
}

export const useUserData = defineLoader(
  async (to) => {
    // ...
  },
  {
    errors: [MyError],
  }
)
```

These can also be specified globally:

```ts{11-13}
class MyError extends Error {
  name = 'MyError'
  constructor(message: string) {
    super(message)
  }
}

app.use(DataLoaderPlugin, {
  router,
// checks with `instanceof MyError`
  errors: [MyError],
})
```

::: tip

In a lazy loader, you can throw an error and since it doesn't block the navigation it will **always** appear in the `error` property. Defining an `errors` property won't change anything.

:::

### Usage outside of page components

Loaders can be attached to a page even if the page component doesn't use it (invoke the composable returned by `defineLoader()`). This is possible if a nested component uses the data. It can be used in any component by importing the *returned composable*, even outside of the scope of the page components, even by a parent.

On top of that, loaders can be **defined anywhere** and imported where using the data makes sense. This allows to define loaders in a separate `src/loaders` folder and reuse them across pages:

```ts
// src/loaders/user.ts
export const useUserData = defineLoader(...)
// ...
```

Then, in a page component, export it:

```vue
<!-- src/pages/users/[id].vue -->
<script>
export { useUserData } from '~/loaders/user.ts'
</script>
<script setup>
// ...
</script>
```

The page component might not even use `useUserData()` but we can still use it anywhere else:

```vue
<!-- src/components/NavBar.vue -->
<script setup>
import { useUserData } from '~/loaders/user.ts'

const { data: user } = useUserData()
</script>
```

::: warning
If you use a loader in a component while it wasn't exported by a page, it won't be awaited during navigation. This can lead to unexpected behavior but it can be caught during development with a warning.
:::

### TypeScript

Types are automatically generated for the routes by [unplugin-vue-router][uvr] and can be referenced with the name of each route to hint `defineLoader()` the possible values of the current types. On top of that, `defineLoader()` infers the returned types:

```vue twoslash
<script lang="ts">
// ---cut-start---
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
// ---cut-end---
import { getUserById } from '../api'

export const useUserData = defineLoader('/users/[id]', async (route) => {
  //                                              ^|

  //
  const user = await getUserById(route.params.id)
  //                                          ^|
  // ...
  return user
})
</script>

<script lang="ts" setup>
const { data: user, isLoading, error } = useUserData()
//            ^?
//            👆 hover or tap
</script>
```

The arguments can be removed during the compilation step in production mode since they are only used for types and are ignored at runtime.

### Non blocking data fetching (Lazy Loaders)

Also known as [lazy async data in Nuxt](https://v3.nuxtjs.org/api/composables/use-async-data), loaders can be marked as lazy to **not block the navigation**.

```vue{10,16-17} twoslash
<script lang="ts">
// ---cut-start---
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
// ---cut-end---
import { getUserById } from '../api'

export const useUserData = defineLoader(
  '/users/[id]',
  async (route) => {
    const user = await getUserById(route.params.id)
    return user
  },
  { lazy: true } // 👈  marked as lazy
)
</script>

<script setup>
// Differently from the example above, `user.value` can and will be initially `undefined`
const { data: user, isLoading, error } = useUserData()
//            ^?
//            👆 hover or tap
</script>
```

This patterns is useful to avoid blocking the navigation while *non critical data* is being fetched. It will display the page earlier while some of the parts of it are still loading and you are able to display loader indicators thanks to the `isLoading` property.

Note this still allows for having different behavior during SSR and client side navigation, e.g.: if we want to wait for the loader during SSR but not during client side navigation:

```ts{6-7}
export const useUserData = defineLoader(
  async (route) => {
    // ...
  },
  {
    lazy: !import.env.SSR, // Vite
    lazy: process.client, // NuxtJS
  }
)
```

Existing questions:

* [~~Should it be possible to await all pending loaders with `await allPendingLoaders()`? Is it useful for SSR? Otherwise we could always ignore lazy loaders in SSR. Do we need both? Do we need to selectively await some of them?~~](https://github.com/vuejs/rfcs/discussions/460#discussioncomment-3532011)
* Should we be able to transform a loader into a lazy version of it: `const useUserDataLazy = asLazyLoader(useUserData)`

### AbortSignal

The loader receives in a second argument access to an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can be passed on to `fetch` and other Web APIs. If the navigation is cancelled because of errors or a new navigation, the signal aborts, causing any request using it to abort as well.

```ts twoslash
import { defineBasicLoader as defineLoader } from 'unplugin-vue-router/data-loaders/basic'
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchBookCollection(options: {
  signal?: AbortSignal
}): Promise<Book[]> {
  return {} as any
}
// ---cut---
export const useBookCollection = defineLoader(async (_route, { signal }) => {
  return fetchBookCollection({ signal })
})
```

This aligns with the future [Navigation API](https://github.com/WICG/navigation-api#navigation-monitoring-and-interception) and other web APIs that use the `AbortSignal` to cancel an ongoing invocation.

### Implementations

### Interfaces

Defining a minimal set of information and options for Data Loaders is what enables external libraries to implement their own data loaders. They are meant to extend these interfaces to add more features that are specific to them. You can see a practical example with the [Pinia Colada](./colada/) implementation.

::: danger
This section is still a work in progress, see the [implementations](#implementations) instead.
:::

### Global API

It's possible to access a global state of when data loaders are fetching (during navigation or when `reload()` is called) as well as when the data fetching navigation guard is running (only when navigating).

* `isFetchingData: Ref<boolean>`: is any loader currently fetching data? e.g. calling the `reload()` method of a loader
* `isNavigationFetching: Ref<boolean>`: is navigation being hold by a loader? (implies `isFetchingData.value === true`). Calling the `reload()` method of a loader doesn't change this.

TBD: is this worth it? Are any other functions needed?

### Limitations

* \~~Injections (`inject`/`provide`) cannot be used within a loader~~ They can now
* Watchers and other composables shouldn't be used within data loaders:
  * if `await` is used before calling a composable e.g. `watch()`, the scope **is not guaranteed**
  * In practice, **this shouldn't be a problem** because there is **no need** to create composables within a loader

## Drawbacks

* At first, it looks less intuitive than just awaiting something inside `setup()` with `<Suspense>` [but it doesn't have its limitations](#suspense) and have many more features
* Requires an extra `<script>` tag but only for page components. A macro `definePageLoader()`/`defineLoader()` could be error-prone as it's very tempting to use reactive state declared within the component's `<script setup>` but that's not possible as the loader must be created outside of its `setup()` function

## Alternatives

### Suspense

Using Suspense is probably the first alternative that comes to mind and it has been considered as a solution for data fetching by implementing proofs of concepts. It however suffers from major drawbacks that are tied to its current design and is not a viable solution for data fetching.

One could imagine being able to write something like:

```vue
<!-- src/pages/users.vue = /users -->
<!-- Displays a list of all users -->
<script setup>
const userList = shallowRef(await fetchUserList())

// manually expose a reload function to be called whenever needed
function reload() {
  userList.value = await fetchUserList()
}
</script>
```

Or when params are involved in the data fetching:

```vue
<!-- src/pages/users.[id].vue = /users/:id -->
<!-- Displays a list of all users -->
<script setup>
const route = useRoute()
const user = shallowRef(await fetchUserData(route.params.id))

// manually expose a reload function to be called whenever needed
function reload() {
  user.value = await fetchUserData(route.params.id)
}

// hook into navigation instead of a watcher because we want to block the navigation
onBeforeRouteUpdate(async (to) => {
  // note how we need to use `to` and not `route` here
  user.value = await fetchUserData(to.params.id)
})
</script>
```

This setup has many limitations:

* Nested routes will force **sequential data fetching**: it's not possible to ensure an **optimal parallel fetching**

* Manual data refreshing is necessary **unless you add a `key` attribute** to the `<RouterView>` which will force a remount of the component on navigation. This is not ideal because it will remount the component on every navigation, even when the data is the same. It's necessary if you want to do a `<transition>` but less flexible than the proposed solution which also works with a `key` if needed.

* By putting the fetching logic within the `setup()` of the component we face other issues:

  * No abstraction of the fetching logic => **code duplication** when fetching the same data in multiple components
  * No native way to deduplicate requests among multiple components using them: it requires using a store and extra logic to skip redundant fetches when multiple components are using the same data
  * Does not block the navigation
    * We can block it by mounting the upcoming page component (while the navigation is still blocked by the data loader navigation guard) which can be **expensive in terms of rendering and memory** as we still need to render the old page while we ***try** to mount the new page*.
  * Cannot modify the output of the navigation (e.g. redirecting, cancelling, etc), if the fetching fails, we end up in an error state

* No native way of caching data, even for very simple cases (e.g. no refetching when fast traveling back and forward through browser UI)

* Not possible to precisely read (or write) the loading state (see [vuejs/core#1347](https://github.com/vuejs/core/issues/1347)])

On top of this it's important to note that this RFC doesn't limit you: you can still use Suspense for data fetching or other async state or even use both, **this API is completely tree shakable** and doesn't add any runtime overhead if you don't use it. Aligning with the progressive enhancement nature of Vue.js.

### Other alternatives

* Allowing blocking data loaders to return objects of properties:

  ::: details

  ```ts
  export const useUserData = defineLoader(async (route) => {
    const user = await getUserById(route.params.id)
    // instead of return user
    return { user }
  })
  // instead of const { data: user } = useUserData()
  const { user } = useUserData()
  ```

  This was the initial proposal but since this is not possible with lazy loaders it was more complex and less intuitive. Having one single version is overall easier to handle. It does allow to return pending promises in the object that aren't awaited:

  ```ts
    export const useUserData = defineLoader(async (route) => {
    return {
      // awaited
      user: await getUserById(route.params.id)
      // not awaited, like lazy
      nonCriticalData: getNonCriticalData() // Promise<...>
    }
  })
  ```

  But this version overlaps with `lazy: true`. While semantically it would be more natural if it was defined with **one** loader, it limits the API to one loader per page and not being able to reuse the data, loading state, error, etc across pages and components, which also limits the extensibility.

  :::

* Adding a new `<script loader>` similar to `<script setup>`:

  ::: details

  ```vue
  <script lang="ts" loader="useUserData">
  import { getUserById } from '~/api/users'
  import { useRoute } from 'vue-router' // could be automatically imported

  const route = useRoute()
  // any variable created here is available in useLoader()
  const user = await getUserById(route.params.id)
  </script>

  <script lang="ts" setup>
  const { user, isLoading, error } = useUserData()
  </script>
  ```

  Too magical without clear benefit.

  :::

* Pass route properties instead of the whole `route` object:

  ::: details

  ```ts
  import { getUserById } from '../api'

  export const useUserData = defineLoader(async ({ params }) => {
    const user = await getUserById(params.id)
    return { user }
  })
  ```

  This has the problem of not being able to use the `route.name` to determine the correct typed params (with [unplugin-vue-router][uvr]):

  ```ts
  import { getUserById } from '../api'

  export const useUserData = defineLoader(async (route) => {
    if (route.name === 'user-details') {
      const user = await getUserById(route.params.id)
      //                                    ^ typed!
      return { user }
    }
  })
  ```

  :::

* Naming

  ::: details

  Variables could be named differently and proposals are welcome:

  * `isLoading` -> `isPending`, `pending` (same as Nuxt)
  * Rename `defineLoader()` to `defineDataFetching()` (or others)

  :::

* Nested/Sequential Loaders drawbacks

  ::: details

  * Allowing `await getUserById()` could make people think they should also await inside `<script setup>` and that would be a problem because it would force them to use `<Suspense>` when they don't need to. I think this is solved by changing the return type of the loader to a promise of just data, making it easy to spot the mistake. It could also be solved by forcing the need of a parameter `to` to ensure the type safety as explained [above](#sequential-fetching).

  * Another alternative is to pass an array of loaders to the loader that needs them and let it retrieve them through an argument, but it feels *considerably* less ergonomic:

    ```ts
    import { useUserData } from '~/pages/users/[id].vue'

    export const useUserFriends = defineLoader(
      async (route, { loaders: [userData] }) => {
        const friends = await getFriends(user.value.id)
        return { ...userData.value, friends }
      },
      {
        // explicit dependencies
        waitFor: [useUserData],
      }
    )
    ```

  :::

* Advanced `lazy`

  ::: details

  The `lazy` flag could be extended to also accept a number (timeout) or a function (dynamic value). I think this is too much and should therefore not be included. It can always be implemented by custom data loaders but I don't think it should be a requirement for the basic API.

  Passing a *number* to `lazy` could block the navigation for that number of milliseconds, then let it be:

  ```vue
  <script lang="ts">
  import { getUserById } from '../api'

  export const useUserData = defineLoader(
    async (route) => {
      const user = await getUserById(route.params.id)
      return user
    },
    // block the navigation for 1 second and then let the navigation go through
    { lazy: 1000 }
  )
  </script>

  <script setup>
  const { data, isLoading, error } = useUserData()
  //      ^ Ref<User | undefined>
  </script>
  ```

  Note that lazy loaders can only control their own blocking mechanism. They can't control the blocking of other loaders. If multiple loaders are being used and one of them is blocking, the navigation will be blocked until all of the blocking loaders are resolved.

  A function could allow to conditionally block upon navigation:

  ```ts
  export const useUserData = defineLoader(
    loader,
    // ...
    {
      lazy: (route) => {
        // ...
        return true // or a number
      },
    }
  )
  ```

  :::

* One could argue being able to reuse the result of loaders across any component other than page makes this more complex. Other frameworks expose a single *load* function from page components (SvelteKit, Remix)

## Adoption strategy

Introduce this as part of [unplugin-vue-router][uvr] to test it first and make it part of the router later on.

## Unresolved questions

* Integration with Server specifics in Frameworks like Nuxt: cookies, headers, server only loaders (can create redirect codes)
* Should there by a `beforeLoad()` hook that is called and awaited before all data loaders
* Same for `afterLoad()` that is always called after all data loaders
* What else is needed besides the `route` inside loaders?
* \~~Add option for placeholder data?~~ Data Loaders should implement this themselves
* What other operations might be necessary for users?

[uvr]: https://github.com/posva/unplugin-vue-router "unplugin-vue-router"

[pinia-colada]: https://github.com/posva/pinia-colada "@pinia/colada"

[vue-query]: https://tanstack.com/query/latest/docs/framework/vue/overview "@tanstack/vue-query"

---

---
url: /data-loaders/defining-loaders.md
---
# Defining Data Loaders

In order to use data loaders, you need to define them first. Data loaders themselves are the composables returned by the different `defineLoader` functions. Each loader definition is specific to the `defineLoader` function used. For example, `defineBasicLoader` expects an async function as the first argument while `defineColadaLoader` expects an object with a `query` function. All loaders should allow to pass an async function that can throw errors, and `NavigationResult`.

Any composables returned by *any* `defineLoader` function share the same signature:

```vue twoslash
<script lang="ts">
import 'unplugin-vue-router/client'
import './typed-router.d'
// ---cut---
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
import { getUserById } from '../api'

export const useUserData = defineBasicLoader('/users/[id]', async (to) => {
  return getUserById(to.params.id)
})
</script>

<script setup lang="ts">
const {
  data: user, // the data returned by the loader
  isLoading, // a boolean indicating if the loader is fetching data
  error, // an error object if the loader failed
  reload, // a function to refetch the data without navigating
} = useUserData()
</script>
```

**But they are not limited by it!** For example, the `defineColadaLoader` function returns a composable with a few more properties like `status` and `refresh`. Because of this it's important to refer to the documentation of the specific loader you are using.

This page will guide you through the **foundation** of defining data loaders, no matter their implementation.

## The loader function

The loader function is the *core* of data loaders. They are asynchronous functions that return the data you want to expose in the `data` property of the returned composable.

### The `to` argument

The `to` argument represents the location object we are navigating to. It should be used as the source of truth for all data fetching parameters.

```ts twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
import { getUserById } from '../api'
// ---cut---
export const useUserData = defineBasicLoader('/users/[id]', async (to) => {
  const user = await getUserById(to.params.id)
  // here we can modify the data before returning it
  return user
})
```

By using the route location to fetch data, we ensure a consistent relationship between the data and the URL, **improving the user experience**.

### Side effects

It's important to avoid side effects in the loader function. Don't call `watch`, or create reactive effects like `ref`, `toRefs()`, `computed`, etc.

### Global Properties

In the loader function, you can access global properties like the router instance, a store, etc. This is because using `inject()` within the loader function **is possible**, just like within navigation guards. Since loaders are asynchronous, make sure you are using the `inject` function **before any `await`**:

```ts twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
import { getUserById } from '../api'
// ---cut---
import { inject } from 'vue'
import { useSomeStore, useOtherStore } from '@/stores'

export const useUserData = defineBasicLoader('/users/[id]', async (to) => {
  // ✅ This will work
  const injectedValue = inject('key') // [!code ++]
  const store = useSomeStore() // [!code ++]

  const user = await getUserById(to.params.id)
  // ❌ These won't work
  const injectedValue2 = inject('key-2') // [!code error]
  const store2 = useOtherStore() // [!code error]
  // ...
  return user
})
```

### Navigation control

Since loaders happen within the context of a navigation, you can control the navigation by returning a `NavigationResult` object. This is similar to returning a value in a navigation guard

```ts{1,8,9}
import { NavigationResult } from 'unplugin-vue-router/data-loaders'

const useDashboardStats = defineBasicLoader('/admin', async (to) => {
  try {
    return await getDashboardStats()
  } catch (err) {
    if (err.code === 401) {
      // same as returning '/login' in a navigation guard
      return new NavigationResult('/login')
    }
    throw err // unexpected error
  }
})
```

::: tip

Note that [lazy loaders](#lazy-loaders) cannot control the navigation since they do not block it.

:::

Read more in the [Navigation Aware](./navigation-aware.md) section.

### Errors

Any thrown Error will abort the navigation, just like in navigation guards. They will trigger the `router.onError` handler if defined.

::: tip

Note that [lazy loaders](#lazy-loaders) cannot control the navigation since they do not block it, any thrown error will appear in the `error` property and not abort the navigation nor appear in the `router.onError` handler.

:::

It's possible to define expected errors so they don't abort the navigation. You can read more about it in the [Error Handling](./error-handling.md) section.

## Options

Data loaders are designed to be flexible and allow for customization. Despite being navigation-centric, they can be used outside of a navigation and this flexibility is key to their design.

### Non blocking loaders with `lazy`

By default, loaders are *non-lazy*, meaning they will block the navigation until the data is fetched. But this behavior can be changed by setting the `lazy` option to `true`.

```vue{10,16} twoslash
<script lang="ts">
// ---cut-start---
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
// ---cut-end---
import { getUserById } from '../api'

export const useUserData = defineBasicLoader(
  '/users/[id]',
  async (to) => {
    const user = await getUserById(to.params.id)
    return user
  },
  { lazy: true } // 👈  marked as lazy
)
</script>

<script setup>
// Differently from the example above, `user.value` can and will be initially `undefined`
const { data: user, isLoading, error } = useUserData()
//            ^?
</script>

<!-- ... -->
```

This patterns is useful to avoid blocking the navigation while *non critical data* is being fetched. It will display the page earlier while lazy loaders are still loading and you are able to display loader indicators thanks to the `isLoading` property.

Since lazy loaders do not block the navigation, any thrown error will not abort the navigation nor appear in the `router.onError` handler. Instead, the error will be available in the `error` property.

Note this still allows for having different behavior during SSR and client side navigation, e.g.: if we want to wait for the loader during SSR but not during client side navigation:

```ts{6-7}
export const useUserData = defineBasicLoader(
  async (to) => {
    // ...
  },
  {
    lazy: !import.meta.env.SSR, // Vite specific
  }
)
```

You can even pass a function to `lazy` to determine if the loader should be lazy or not based on each load/navigation:

```ts{6-7}
export const useSearchResults = defineBasicLoader(
  async (to) => {
    // ...
  },
  {
    // lazy if we are on staying on the same route
    lazy: (to, from) => to.name === from.name,
  }
)
```

This is really useful when you can display the old data while fetching the new one and some of the parts of the page require the route to be updated like search results and pagination buttons. By using a lazy loader only when the route changes, the pagination can be updated immediately while the search results are being fetched, allowing the user to click multiple times on the pagination buttons without waiting for the search results to be fetched.

### Delaying data updates with `commit`

By default, the data is updated only once all loaders are resolved. This is useful to avoid displaying partially loaded data or worse, incoherent data aggregation.

Sometimes you might want to immediately update the data as soon as it's available, even if other loaders are still pending. This can be achieved by changing the `commit` option:

```ts twoslash
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchBookCollection(): Promise<Book[]> {
  return {} as any
}
// ---cut---
export const useBookCollection = defineBasicLoader(fetchBookCollection, {
  commit: 'immediate',
})
```

In the case of [lazy loaders](#lazy-loaders), they also default to `commit: 'after-load'`. They will commit after all other non-lazy loaders if they can but since they are not awaited, they might not be able to. In this case, the data will be available when finished loading, which can be much later than the navigation is completed.

### Server optimization with `server`

During SSR, it might be more performant to avoid loading data that isn't critical for the initial render. This can be achieved by setting the `server` option to `false`. That will completely skip the loader during SSR.

```ts{3} twoslash
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchRelatedBooks(id: string | string[]): Promise<Book[]> {
  return {} as any
}
// ---cut---
export const useRelatedBooks = defineBasicLoader(
  (to) => fetchRelatedBooks(to.params.id),
  { server: false }
)
```

You can read more about server side rendering in the [SSR](./ssr.md) section.

## Connecting a loader to a page

The router needs to know what loaders should be ran with which page. This is achieved in two ways:

* **Automatically**: when a loader is exported from a page component that is lazy loaded, the loader will be automatically connected to the page

  ::: code-group

  ```ts{8} [router.ts]
  import { createRouter, createWebHistory } from 'vue-router'

  export const router = createRouter({
    history: createWebHistory(),
    routes: [
      {
        path: '/settings',
        component: () => import('./settings.vue'),
      },
    ],
  })
  ```

  ```vue{3-5} [settings.vue]
  <script lang="ts">
  import { getSettings } from './api'
  export const useSettings = defineBasicLoader('/settings', async (to) =>
    getSettings()
  )
  </script>

  <script lang="ts" setup>
  const { data: settings } = useSettings()
  </script>
  <!-- ...rest of the component -->
  ```

  :::

* **Manually**: by passing the defined loader into the `meta.loaders` property:

  ::: code-group

  ```ts{2,10-12} [router.ts]
  import { createRouter, createWebHistory } from 'vue-router'
  import Settings, { useSettings } from './settings.vue'

  export const router = createRouter({
    history: createWebHistory(),
    routes: [
      {
        path: '/settings',
        component: Settings,
        meta: {
          loaders: [useSettings],
        },
      }
    ],
  })
  ```

  ```vue{3-5} [settings.vue]
  <script lang="ts">
  import { getSettings } from './api'
  export const useSettings = defineBasicLoader('/settings', async (to) =>
    getSettings()
  )
  </script>

  <script lang="ts" setup>
  const { data: settings } = useSettings()
  </script>
  <!-- ...rest of the component -->
  ```

### *Disconnecting* a loader from a page

It is also possible **not to connect a loader to a page**. This allows you to delay the loading until the component is mounted. Usually you want to start loading the data as soon as possible but in some cases, it might be better to wait until the component is mounted. This can be achieved by not exporting the loader from the page component.

---

---
url: /data-loaders/error-handling.md
---
# Error handling

By default, all errors thrown in a loader are considered *unexpected errors*: they will abort the navigation, just like in a navigation guard. Because they abort the navigation, they will not appear in the `error` property of the loader. Instead, they will be intercepted by Vue Router's error handling with `router.onError()`.

However, if the loader is **not navigation-aware**, the error cannot be intercepted by Vue Router and will be kept in the `error` property of the loader. This is the case for *lazy loaders* and [*reloading data*](./reloading-data.md).

## Defining expected Errors

To be able to intercept errors in non-lazy loaders, we can specify a list of error classes that are considered *expected errors*. This allows blocking loader to **not abort the navigation** and instead keep the error in the `error` property of the loader and let the page locally display the error state.

```ts{3-10,14,18} twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
// @moduleResolution: bundler
// ---cut---
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
// custom error class
class MyError extends Error {
  // override is only needed in TS
  override name = 'MyError' // Displays in logs instead of 'Error'
  // defining a constructor is optional
  constructor(message: string) {
    super(message)
  }
}

export const useUserData = defineBasicLoader(
  async (to) => {
    throw new MyError('Something went wrong')
    // ...
    // ---cut-start---
    return { name: 'John' }
    // ---cut-end---
  },
  {
    errors: [MyError],
  }
)
```

You can also specify *expected errors* globally for all loaders by providing the `errors` option to the `DataLoaderPlugin`.

```ts{4} twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { createApp } from 'vue'
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders'
const app = createApp({})
const router = {} as any
class MyError extends Error {
  name = 'MyError'
  constructor(message: string) {
    super(message)
  }
}
// @moduleResolution: bundler
// ---cut---
app.use(DataLoaderPlugin, {
  router,
  // checks with `instanceof MyError`
  errors: [MyError],
})
```

Then you need to opt-in in the loader by setting the `errors` option to `true` to keep the error in the `error` property of the loader.

```ts{7} twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
// @moduleResolution: bundler
// ---cut---
export const useUserData = defineBasicLoader(
  async (to) => {
    throw new Error('Something went wrong')
    // ...
    // ---cut-start---
    return { name: 'John' }
    // ---cut-end---
  },
  {
    errors: true,
  }
)
```

::: details Why is `errors: true` needed?

One of the benefits of Data Loaders is that they ensure the `data` to be ready before the component is rendered. With expected errors, this is no longer true and `data` can be `undefined`:

```ts{11} twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
// @moduleResolution: bundler
// ---cut---
export const useDataWithErrors = defineBasicLoader(
  async (to) => {
    // ...
    // ---cut-start---
    return { name: 'John' }
    // ---cut-end---
  },
  {
    errors: true,
  }
)

const { data } = useDataWithErrors()
data.value // `data` can be `undefined`
```

:::

## Custom Error handling

If you need more control over the error handling, you can provide a function to the `errors` option. This option is available in both the `DataLoaderPlugin` and when defining a loader.

```ts{3-9} twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { createApp } from 'vue'
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders'
const app = createApp({})
const router = {} as any
// @moduleResolution: bundler
// ---cut---
app.use(DataLoaderPlugin, {
  router,
  errors: (error) => {
    // Convention for custom errors
    if (error instanceof Error && error.name?.startsWith('My')) {
      return true
    }
    return false // unexpected error
  },
})
```

## Handling both, local and global errors

TODO: this hasn't been implemented yet

## Error handling priority

When you use both, global and local error handling, the local error handling has a higher priority and will override the global error handling. This is how the local and global errors are checked:

* if local `errors` is `false`: abort the navigation -> `data` is not `undefined`
* if local `errors` is `true`: rely on the globally defined `errors` option -> `data` is possibly `undefined`
* else: rely on the local `errors` option -> `data` is possibly `undefined`

## TypeScript

You will notice that the type of `error` is `Error | null` even when you specify the `errors` option. This is because if we call the `reload()` method (meaning we are outside of a navigation), the error isn't discarded, it appears in the `error` property **without being filtered** by the `errors` option.

In practice, depending on how you handle the error, you will add a [type guard](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards) inside the component responsible for displaying an error or directly in a `v-if` in the template.

```vue-html
<template>
  <!-- ... -->
  <p v-if="isMyError(error)">{{ error.message }}</p>
</template>
```

If you want to be even stricter, you can override the default `Error` type with `unknown` (or anything else) by augmenting the `TypesConfig` interface.

```ts
// types-extension.d.ts
import 'unplugin-vue-router/data-loaders'
export {}
declare module 'unplugin-vue-router/data-loaders' {
  interface TypesConfig {
    Error: unknown
  }
}
```

---

---
url: /guide/eslint.md
---
# ESlint

If you are not using auto imports, you will need to tell ESlint about `vue-router/auto-routes`. Add these lines to your eslint configuration:

```json{3}
{
  "settings": {
    "import/core-modules": ["vue-router/auto-routes"]
  }
}
```

## `definePage()`

Since `definePage()` is a global macro, you need to tell ESlint about it. Add these lines to your eslint configuration:

```json{3}
{
  "globals": {
    "definePage": "readonly"
  }
}
```

---

---
url: /guide/extending-routes.md
---
# Extending Routes

## Extending routes in config

You can extend the routes at build time with the `extendRoute` or the `beforeWriteFiles` options. Both can return a Promise:

````ts twoslash
import VueRouter from 'unplugin-vue-router/vite'
import path from 'node:path'
/**
 * In ESM environments, you can use `import.meta.url` to get the current file path:
 *
 * ```ts
 * import { dirname } from 'node:path'
 * import { fileURLToPath } from 'node:url'
 *
 * const __filename = fileURLToPath(import.meta.url)
 * const __dirname = dirname(__filename)
 * ```
 */
const __dirname: string = '...'
// ---cut---
// @moduleResolution: bundler
VueRouter({
  extendRoute(route) {
    if (route.name === '/[name]') {
      route.addAlias('/hello-vite-:name')
    }
  },

  beforeWriteFiles(root) {
    root.insert('/from-root', path.join(__dirname, './src/pages/index.vue'))
  },
})
````

Routes modified this way will be reflected in the generated `typed-router.d.ts` file.

## In-Component Routing

It's possible to override the route configuration directly in the page component file. These changes are picked up by the plugin and reflected in the generated `typed-router.d.ts` file.

### `definePage()`

You can modify and extend any page component with the `definePage()` macro. This is useful for adding meta information, or modifying the route object. It's globally available in Vue components but you can import it from `unplugin-vue-router/runtime` if needed.

```vue{2-7} twoslash
<script setup lang="ts">
// ---cut-start---
import 'unplugin-vue-router/client'
import './typed-router.d'
export {}
// ---cut-end---
// @errors: 2322 2339
// @moduleResolution: bundler
definePage({
  alias: ['/n/:name'],
  meta: {
    requiresAuth: true,
  },
})
</script>

<template>
  <!-- ... -->
</template>
```

If you are using ESLint, you will need [to declare it as a global variable](../guide/eslint.md#definepage).

::: danger
You cannot use variables in `definePage()` as its passed parameter gets extracted at build time and is removed from `<script setup>`. Similar to other macros like `definePageMeta()` in Nuxt.
:::

### SFC `<route>` custom block

The `<route>` custom block is a way to extend existing routes. It can be used to add new `meta` fields, override the `path`, the `name`, or anything else in a route. **It has to be added to a `.vue` component inside of the [routes folder](#routes-folder-structure)**. It is similar to [the same feature in vite-plugin-pages](https://github.com/hannoeru/vite-plugin-pages#sfc-custom-block-for-route-data) to facilitate migration.

```vue
<route lang="json">
{
  "name": "name-override",
  "meta": {
    "requiresAuth": false
  }
}
</route>
```

Note you can specify the language to use with `<route lang="yaml">`. By default, the language is JSON5 (more flexible version of JSON) but yaml and JSON are also supported.

## Extending routes at runtime

As an escape-hatch, it's possible to extend the routes **at runtime** by simply changing or cloning the `routes` array before passing it to `createRouter()`. Since these changes are made at runtime, they are not reflected in the generated `typed-router.d.ts` file.

```js{4-9}
import { createWebHistory, createRouter } from 'vue-router'
import { routes } from 'vue-router/auto-routes'

for (const route of routes) {
  if (route.name === '/admin') {
    route.meta ??= {}
    route.meta.requiresAuth = true
  }
}

const router = createRouter({
  history: createWebHistory(),
  routes,
})
```

::: warning
Routes added at runtime [require special handling for HMR](./hmr.md#runtime-routes).
:::

As this plugin evolves, this should be used less and less and only become necessary in specific scenarios.

One example of this is using [vite-plugin-vue-layouts](https://github.com/JohnCampionJr/vite-plugin-vue-layouts) which can only be used this way:

```ts
import { createRouter } from 'vue-router'
import { routes } from 'vue-router/auto-routes'
import { setupLayouts } from 'virtual:generated-layouts'

const router = createRouter({
  // ...
  routes: setupLayouts(routes),
})
```

Another one is adding *redirect* records to the router:

```ts
import { routes } from 'vue-router/auto-routes'

routes.push({
  path: '/path-to-redirect',
  redirect: '/redirected-path',
})

routes.push({
  path: '/path-to-redirect/:id',
  redirect: (to) => `/redirected-path/${to.params.id}`,
})
```

One benefit of adding redirects at runtime only is that they are not reflected in the generated `typed-router.d.ts` and won't appear in autocompletion but will still work as expected when the user enters the URL or clicks on a link.

---

---
url: /guide/file-based-routing.md
---
# File based routing

The file based routing is as close as possible to [Nuxt](https://nuxt.com/docs/guide/directory-structure/pages).

## Routes folder structure

By default, this plugins checks the folder at `src/pages` for any `.vue` files and generates the corresponding routing structure basing itself in the file name. This way, you no longer need to maintain a `routes` array when adding routes to your application, **instead just add the new `.vue` component to the routes folder and let this plugin do the rest!**

Let's take a look at a simple example:

```text
src/pages/
├── index.vue
├── about.vue
└── users/
    ├── index.vue
    └── [id].vue
```

This will generate the following routes:

* `/`: -> renders the `index.vue` component
* `/about`: -> renders the `about.vue` component
* `/users`: -> renders the `users/index.vue` component
* `/users/:id`: -> renders the `users/[id].vue` component. `id` becomes a route param.

### Index Routes

Any `index.vue` (**must be all lowercase**) file will generate an empty path (similar to `index.html` files):

* `src/pages/index.vue`: generates a `/` route
* `src/pages/users/index.vue`: generates a `/users` route

### Nested Routes

Nested routes are automatically defined by defining a `.vue` file alongside a folder **with the same name**. If you create both a `src/pages/users/index.vue` and a `src/pages/users.vue` components, the `src/pages/users/index.vue` will be rendered within the `src/pages/users.vue`'s `<RouterView>`.

In other words, given this folder structure:

```text
src/pages/
├── users/
│   └── index.vue
└── users.vue
```

You will get this `routes` array:

```js
const routes = [
  {
    path: '/users',
    component: () => import('src/pages/users.vue'),
    children: [
      { path: '', component: () => import('src/pages/users/index.vue') },
    ],
  },
]
```

While omitting the `src/pages/users.vue` component will generate the following routes:

```js
const routes = [
  {
    path: '/users',
    // notice how there is no component here
    children: [
      { path: '', component: () => import('src/pages/users/index.vue') },
    ],
  },
]
```

Note the folder and file's name `users/` could be any valid naming like `my-[id]-param/`.

#### Nested routes without nesting layouts

Sometimes you might want to add *nesting to the URL* in the form of slashes but you don't want it to impact your UI hierarchy. Consider the following folder structure:

```text
src/pages/
├── users/
│   ├── [id].vue
│   └── index.vue
└── users.vue
```

If you want to add a new route `/users/create` you could add a new file `src/pages/users/create.vue` but that would nest the `create.vue` component within the `users.vue` component. To avoid this you can instead create a file `src/pages/users.create.vue`. The `.` will become a `/` when generating the routes:

```js
const routes = [
  {
    path: '/users',
    component: () => import('src/pages/users.vue'),
    children: [
      { path: '', component: () => import('src/pages/users/index.vue') },
      { path: ':id', component: () => import('src/pages/users/[id].vue') },
    ],
  },
  {
    path: '/users/create',
    component: () => import('src/pages/users.create.vue'),
  },
]
```

### Named routes

All generated routes that have a `component` property will have a `name` property. This avoid accidentally directing your users to a parent route. By default, names are generated using the file path, but you can override this behavior by passing a custom `getRouteName()` function. You will get TypeScript validation almost everywhere, so changing this should be easy.

## Route groups

Sometimes, it helps to organize your file structure in a way that doesn't change the URL of your routes. Route groups let you organize your routes logically, in a way that makes sense to you, without affecting the actual URLs. For example, if you have several routes that share the same layout, you can group them together using route groups. Consider the following file structure:

```text
src/pages/
├── (admin)/
│   ├── dashboard.vue
│   └── settings.vue
└── (user)/
    ├── profile.vue
    └── order.vue
```

Resulting URLs:

```text
- `/dashboard` -> renders `src/pages/(admin)/dashboard.vue`
- `/settings` -> renders `src/pages/(admin)/settings.vue`
- `/profile` -> renders `src/pages/(user)/profile.vue`
- `/order` -> renders `src/pages/(user)/order.vue`
```

This approach allows you to organize your files for better maintainability without changing the structure of your application's routes.

You can also use route groups in page components. This is equivalent to name the page component `index.vue`:

```text
src/pages/
└─── admin/
    ├── (dashboard).vue // Becomes index.vue of admin route
    └── settings.vue
```

## Named views

It is possible to define [named views](https://router.vuejs.org/guide/essentials/named-views.html#named-views) by appending an `@` + a name to their filename, e.g. a file named `src/pages/index@aux.vue` will generate a route of:

```js
{
  path: '/',
  component: {
    aux: () => import('src/pages/index@aux.vue')
  }
}
```

Note that by default a non named route is named `default` and that you don't need to name your file `index@default.vue` even if there are other named views (e.g. having `index@aux.vue` and `index.vue` is the same as having `index@aux.vue` and `index@default.vue`).

## Dynamic Routes

You can add [route params](https://router.vuejs.org/guide/essentials/dynamic-matching.html) by wrapping the *param name* with brackets, e.g. `src/pages/users/[id].vue` will create a route with the following path: `/users/:id`. Note you can add a param in the middle in between static segments: `src/pages/users_[id].vue` -> `/users_:id`. You can even add multiple params: `src/pages/product_[skuId]_[seoDescription].vue`.

You can create [**optional params**](https://router.vuejs.org/guide/essentials/route-matching-syntax.html#optional-parameters) by wrapping the *param name* with an extra pair of brackets, e.g. `src/pages/users/[[id]].vue` will create a route with the following path: `/users/:id?`.

You can create [**repeatable params**](https://router.vuejs.org/guide/essentials/route-matching-syntax.html#repeatable-params) by adding a plus character (`+`) after the closing bracket, e.g. `src/pages/articles/[slugs]+.vue` will create a route with the following path: `/articles/:slugs+`.

And you can combine both to create optional repeatable params, e.g. `src/pages/articles/[[slugs]]+.vue` will create a route with the following path: `/articles/:slugs*`.

## Catch all / 404 Not found route

To create a catch all route prepend 3 dots (`...`) to the param name, e.g. `src/pages/[...path].vue` will create a route with the following path: `/:path(.*)`. This will match any route. Note this can be done inside a folder too, e.g. `src/pages/articles/[...path].vue` will create a route with the following path: `/articles/:path(.*)`.

## Multiple routes folders

It's possible to provide multiple routes folders by passing an array to `routesFolder`:

```js
VueRouter({
  routesFolder: ['src/pages', 'src/admin/routes'],
})
```

You can also provide a path prefix for each of these folders, it will be used *as is*, and **cannot start with a `/`** but can contain any params you want or even **not finish with a `/`**:

```ts twoslash
import VueRouter from 'unplugin-vue-router/vite'
// ---cut---
// @moduleResolution: bundler
VueRouter({
  routesFolder: [
    'src/pages',
    {
      src: 'src/admin/routes',
      // note there is always a trailing slash and never a leading one
      path: 'admin/',
      // src/admin/routes/dashboard.vue -> /admin/dashboard
    },
    {
      src: 'src/docs',
      // you can add parameters
      path: 'docs/:lang/',
      // src/docs/introduction.vue -> /docs/:lang/introduction
    },
    {
      src: 'src/promos',
      // you can omit the trailing slash
      path: 'promos-',
      // src/promos/black-friday.vue -> /promos-black-friday
    },
  ],
})
```

Note that the provided folders must be separate and one *route folder* cannot contain another specified *route folder*. If you need further customization, give [definePage()](extending-routes#definepage) a try.

## Custom extensions

While most of the time you will be using `.vue` files, you can also specify custom extensions to be considered as pages. You can for example use *markdown* files as pages:

```ts twoslash
import VueRouter from 'unplugin-vue-router/vite'
// ---cut---
// @moduleResolution: bundler
VueRouter({
  // globally set the extensions
  extensions: ['.vue', '.md'],
  routesFolder: [
    'src/pages',
    {
      src: 'src/docs',
      // override the global extensions to **only** accept markdown files
      extensions: ['.md'],
    },
  ],
})
```

In this scenario, files named `index.md` (**must be all lowercase**) will generate an empty path like `index.vue` files.

---

---
url: /guide/hmr.md
---
# Hot Module Replacement

When using `definePage()` and `<route>` blocks, it's possible to enable Hot Module Replacement (HMR) for your routes **and avoid the need of reloading the page or the server** when you make changes to your routes.

Enabling HMR is **strongly recommended** and currently **only works with Vite**.

```ts [src/router.ts]
import { createRouter, createWebHistory } from 'vue-router'
import {
  routes,
  handleHotUpdate, // [!code ++]
} from 'vue-router/auto-routes'

export const router = createRouter({
  history: createWebHistory(),
  routes,
})

// This will update routes at runtime without reloading the page
if (import.meta.hot) { // [!code ++]
  handleHotUpdate(router) // [!code ++]
} // [!code ++]
```

## Runtime routes

If you add routes at runtime, you will have to add them within a callback to ensure they are added during development.

```ts{16-23} [src/router.ts]
import { createRouter, createWebHistory } from 'vue-router'
import { routes, handleHotUpdate } from 'vue-router/auto-routes'

export const router = createRouter({
  history: createWebHistory(),
  routes,
})

function addRedirects() {
  router.addRoute({
    path: '/new-about',
    redirect: '/about?from=/new-about',
  })
}

if (import.meta.hot) {
  handleHotUpdate(router, (newRoutes) => {
    addRedirects()
  })
} else {
  // production
  addRedirects()
}
```

This is **optional**, you can also just reload the page.

---

---
url: /introduction.md
---
# Introduction

## Installation

Install using your favorite package manager:

```bash
npm install -D unplugin-vue-router
```

Add the plugin to your bundler:

::: code-group

```ts [vite.config.ts]
import VueRouter from 'unplugin-vue-router/vite'

export default defineConfig({
  plugins: [
    VueRouter({
      /* options */
    }),
    // ⚠️ Vue must be placed after VueRouter()
    Vue(),
  ],
})
```

```ts [rollup.config.js]
import VueRouter from 'unplugin-vue-router/rollup'

export default {
  plugins: [
    VueRouter({
      /* options */
    }),
    // ⚠️ Vue must be placed after VueRouter()
    Vue(),
  ],
}
```

```ts [webpack.config.js]
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-vue-router/webpack')({
      /* options */
    }),
  ],
}
```

```ts [vue.config.js]
module.exports = {
  configureWebpack: {
    plugins: [
      require('unplugin-vue-router/webpack')({
        /* options */
      }),
    ],
  },
}
```

```ts [esbuild.config.js]
import { build } from 'esbuild'
import VueRouter from 'unplugin-vue-router/esbuild'

build({
  plugins: [VueRouter()],
})
```

:::

## Setup

After adding this plugin, **start the dev server** (usually `npm run dev`) **to generate the first version of the types** at `typed-router.d.ts` which should be added to your `tsconfig.json` along with `"moduleResolution": "Bundler"`. This is what it should look like:

::: code-group

```json{8} [tsconfig.json]
{
  "include": [
    // other files...
    "./typed-router.d.ts" // [!code ++]
  ],
  "compilerOptions": {
    // ...
    "moduleResolution": "Bundler",
    // ...
  }
}
```

```ts [typed-router.d.ts]
/* eslint-disable */
/* prettier-ignore */
// @ts-nocheck
// Generated by unplugin-vue-router. ‼️ DO NOT MODIFY THIS FILE ‼️
// It's recommended to commit this file.
// Make sure to add this file to your tsconfig.json file as an "includes" or "files" entry.

declare module 'vue-router/auto-routes' {
  import type {
    RouteRecordInfo,
    ParamValue,
    ParamValueOneOrMore,
    ParamValueZeroOrMore,
    ParamValueZeroOrOne,
  } from 'vue-router'

  /**
   * Route name map generated by unplugin-vue-router
   */
  export interface RouteNamedMap {
    '/': RouteRecordInfo<
      '/',
      '/',
      Record<never, never>,
      Record<never, never>,
      | never
    >
    '/about': RouteRecordInfo<
      '/about',
      '/about',
      Record<never, never>,
      Record<never, never>,
      | never
    >
    '/users/[id]': RouteRecordInfo<
      '/users/[id]',
      '/users/:id',
      { id: ParamValue<true> },
      { id: ParamValue<false> },
      | never
    >
  }
}
```

:::

Then, if you have an `env.d.ts` file like the one created by `npm vue create <my-project>`, add the `unplugin-vue-router/client` types to it:

::: code-group

```ts{2} [env.d.ts]
/// <reference types="vite/client" />
/// <reference types="unplugin-vue-router/client" />
```

:::

If you don't have an `env.d.ts` file, you can create one and add the unplugin-vue-router types to it *or* you can add them to the `types` property in your `tsconfig.json`:

::: code-group

```json [tsconfig.json]
{
  "compilerOptions": {
    // ...
    "types": [
      "unplugin-vue-router/client" // [!code ++]
    ]
  }
}
```

:::

### Migrating an existing project

Move your page components to `src/pages` and rename them accordingly. Here is an example of migration.
Given the following route configuration:

::: code-group

```ts [src/router.ts]
import { createRouter, createWebHistory } from 'vue-router'
import { routes, handleHotUpdate } from 'vue-router/auto-routes' // [!code ++]

export const router = createRouter({
  history: createWebHistory(),
  routes: [ // [!code --]
    { // [!code --]
      path: '/', // [!code --]
      component: () => import('src/pages/Home.vue'), // [!code --]
    }, // [!code --]
    { // [!code --]
      path: '/users/:id', // [!code --]
      component: () => import('src/pages/User.vue'), // [!code --]
    } // [!code --]
    { // [!code --]
      path: '/about', // [!code --]
      component: () => import('src/pages/About.vue'), // [!code --]
    }, // [!code --]
  ] // [!code --]
  routes, // [!code ++]
})

// This will update routes at runtime without reloading the page
if (import.meta.hot) { // [!code ++]
  handleHotUpdate(router) // [!code ++]
} // [!code ++]
```

```ts{2,5} [main.ts]
import { createApp } from 'vue'
import { router } from './router'
import App from './App.vue'

createApp(App).use(router).mount('#app')
```

:::

* Rename `src/pages/Home.vue` to `src/pages/index.vue`
* Rename `src/pages/User.vue` to `src/pages/users/[id].vue`
* Rename `src/pages/About.vue` to `src/pages/about.vue`

Check the [file-based routing](/guide/file-based-routing) guide for more information about the naming conventions.

### From scratch

* Create a `src/pages` folder and add an `index.vue` component to it. This will render your home page at `/`.
* Import the `routes` from `vue-router/auto-routes` and pass them to the `createRouter` function.

::: code-group

```ts{2-3,6-9,12} [src/main.ts]
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { routes } from 'vue-router/auto-routes'
import App from './App.vue'

const router = createRouter({
  history: createWebHistory(),
  routes,
})

createApp(App)
  .use(router)
  .mount('#app')
```

```vue [src/pages/index.vue]
<template>
  <h1>Home</h1>
</template>
```

:::

Check the [file-based routing](/guide/file-based-routing) guide for more information about the naming conventions.

### Manipulating the routes

You can pass the `routes` to any plugin that needs to add changes to them but note that **these changes will not be reflected in types**. Use [build-time routes instead](./guide/extending-routes.md) if you want to have types support. Here is an example with [Vitesse starter](https://github.com/antfu-collective/vitesse/blob/main/src/main.ts):

```ts
import { ViteSSG } from 'vite-ssg'
import { setupLayouts } from 'virtual:generated-layouts'
import App from './App.vue'
import type { UserModule } from './types'
import generatedRoutes from '~pages' // [!code --]
import { routes } from 'vue-router/auto-routes' // [!code ++]

import '@unocss/reset/tailwind.css'
import './styles/main.css'
import 'uno.css'

const routes = setupLayouts(generatedRoutes) // [!code --]

// https://github.com/antfu/vite-ssg
export const createApp = ViteSSG(
  App,
  {
    routes, // [!code --]
    routes: setupLayouts(routes), // [!code ++]
    base: import.meta.env.BASE_URL,
  },
  (ctx) => {
    // install all modules under `modules/`
    Object.values(
      import.meta.glob<{ install: UserModule }>('./modules/*.ts', {
        eager: true,
      })
    ).forEach((i) => i.install?.(ctx))
  }
)
```

### Auto Imports

If you are using [unplugin-auto-import](https://github.com/unplugin/unplugin-auto-import), make sure to remove the `vue-router` preset and use the one exported by `unplugin-vue-router`:

```ts
import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
import { VueRouterAutoImports } from 'unplugin-vue-router' // [!code ++]

export default defineConfig({
  plugins: [
    // other plugins
    AutoImport({
      imports: [
        'vue-router', // [!code --]
        VueRouterAutoImports, // [!code ++]
      ],
    }),
  ],
})
```

If you use ESlint, check [the ESlint section](/guide/eslint).
If you use TypeScript or have a `jsconfig.json` file, check [the TypeScript section](/guide/typescript).

---

---
url: /data-loaders/organization.md
---
# Loaders Organization

While most examples show loaders defined in the same file as the page component, it's possible to define them in separate files and import them in the page component. This flexibility allows you to control not only the codebase organization but also **how chunks are split**.

If a loader is used in multiple pages, it might be a better idea to extract it to a separate file instead of exporting it in one page and importing it in the others. This is because pages importing it will usually load the whole page component chunk in order to get the loader.

::: code-group

```ts [loaders/issues.ts]
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
import { getIssuesByProjectId } from '@/api'

export const useProjectIssues = defineBasicLoader('/[projectId]/issues', (to) =>
  getIssuesByProjectId(to.params.projectId)
)
```

```vue{2-3,7} [pages/[projectId]/issues.vue]
<script lang="ts">
import { useProjectIssues } from '@/loaders/issues'
export { useProjectIssues }
</script>

<script setup lang="ts">
const { data: issues } = useProjectIssues()
</script>
```

```vue{2,4,9} [pages/[projectId]/insights.vue]
<script lang="ts">
import { useProjectIssues } from '@/loaders/issues'
import { useProjectPullRequests } from '@/loaders/pull-requests'
export { useProjectIssues, useProjectPullRequests }
</script>

<script setup lang="ts">
const { data: issues } = useProjectIssues()
const { data: pullRequests } = useProjectPullRequests()
</script>
```

:::

In the example above, the `useProjectIssues` loader is defined in a separate file and imported in two different pages, `pages/[projectId]/issues.vue` and `pages/[projectId]/insights.vue`. They both use the same data but present it in a different way so there is no reason to create two different loaders for issues. By extracting the loader into a separate file, we ensure an optimal chunk split.

When using this pattern, remember to **export the loader** in all the page components that use it. This is what allows the router to await the loader before rendering the page.

## Usage outside of page components

Until now, we have only seen loaders used in page components. However, one of the benefits of using loaders is that they can be **reused in many parts of your application**, just like regular composables. This will not only eliminate code duplication but also ensure an optimal and performant data fetching by **deduplicating requests and sharing the data**.

To use a loader outside of a page component, you can simply **import it** and use it like any other composable, without the need to export it.

```vue
<script setup lang="ts">
// You can even import it from the page component
import { useProjectIssues } from '@/pages/[projectId]/issues.vue'

const { data: issues } = useProjectIssues()
</script>
```

::: tip

When using a loader in a non-page component, you must **export the loader** from the page components where it is used. If you only import and use the loader in a regular component, the router will not recognize it and won't trigger or await it during navigation.

:::

## Nested Routes

When defining nested routes, you don't need to worry about exporting the loader in both the parent and the child components. This will be automatically optimized for you and the loader will be shared between the parent and the child components.
Because of this, it's simpler to **always export data loaders** in the page component where **they are used**.

---

---
url: /data-loaders/navigation-aware.md
---
# Navigation aware

Since the data fetching happens within a navigation guard, it's possible to control the navigation like in regular navigation guards:

* Thrown errors (or rejected Promises) cancel the navigation (same behavior as in a regular navigation guard) and are intercepted by [Vue Router's error handling](https://router.vuejs.org/api/interfaces/router.html#onerror)
* By returning a `NavigationResult`, you can redirect, cancel, or modify the navigation

Any other returned value is considered as the *resolved data* and will appear in the `data` property.

## Controlling the navigation with `NavigationResult`

`NavigationResult` is a class that can be returned or thrown from a loader to *change* the navigation. It accepts the same arguments as the [return value of a navigation guard](https://router.vuejs.org/guide/advanced/navigation-guards.html#Global-Before-Guards) **as long as it changes the navigation**. It doesn't accept `true` or `undefined` as these values do not change the navigation.

```ts{1,6-8,16,18}
import { NavigationResult } from 'unplugin-vue-router/data-loaders'
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'

export const useUserData = defineBasicLoader(
  async (to) => {
    // cancel the navigation for invalid IDs
    if (isInvalidId(to.params.id)) {
      return new NavigationResult(false)
    }

    try {
      const user = await getUserById(to.params.id)

      return user
    } catch (error) {
      if (error.status === 404) {
        return new NavigationResult({ name: 'not-found' })
      } else {
        throw error // aborts the router navigation
      }
    }
  }
)
```

### Handling multiple navigation results

Since navigation loaders can run in parallel, they can return different navigation results as well. In this case, you can decide which result should be used by providing a `selectNavigationResult()` method to the [`DataLoaderPlugin`](./index.md#installation):

```ts{3-6} twoslash
import 'unplugin-vue-router/client'
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders'
const app = createApp({})
const router = createRouter({
  history: createWebHistory(),
  routes: [],
})
// ---cut---
// @moduleResolution: bundler
// @noErrors
app.use(DataLoaderPlugin, {
  router,
  selectNavigationResult(results) {
    for (const { value } of results) {
      // If any of the results is a redirection to the not-found page, use it
      if (
        typeof value === 'object' &&
        'name' in value &&
        value.name === 'not-found'
      ) {
        return value
      }
    }
  },
})
```

`selectNavigationResult()` is called with an array of all the returned `new NavigationResult(value)` **after all data loaders** have been resolved. **If any of them throws an error** or if none of them return a `NavigationResult`, `selectNavigationResult()` isn't called.

By default, `selectNavigation` returns the first value of the array.

### Eagerly changing the navigation

If a loader wants to eagerly alter the navigation, it can `throw` the `NavigationResult` instead of returning it. This skips the `selectNavigationResult()` and take precedence without triggering `router.onError()`.

```ts{11-16}
import { NavigationResult } from 'unplugin-vue-router/data-loaders'
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'

export const useUserData = defineBasicLoader(
  async (to) => {
    try {
      const user = await getUserById(to.params.id)

      return user
    } catch (error) {
      throw new NavigationResult({
        name: 'not-found',
        // keep the current path in the URL
        params: { pathMatch: to.path.split('/') },
        query: to.query,
        hash: to.hash,
      })
    }
  }
)
```

## Consistent updates

During a navigation, data loaders are grouped together like a *pack*. If the navigation is canceled, none of the results are used. This avoids having partial data updates in a page and inconsistencies between the URL and the page content. On the other hand, if the navigation is successful, all the data loaders are resolved together and the data is only updated **once all the loaders are resolved**. This is true even for lazy loaders. This ensures that even if you have loaders that are really fast, the old data is not displayed until all the loaders are resolved and the new data is completely ready to be displayed.

## Lazy loaders

Apart from consistent updates, lazy loaders are not navigation-aware. They cannot control the navigation with errors or `NavigationResult`. They still start loading as soon as the navigation is initiated.

## Loading after the navigation

It's possible to not start loading the data until the navigation is done. To do this, simply [**do not attach the loader to the page**](./defining-loaders.md#disconnecting-a-loader-from-a-page). It will eventually start loading when the page is mounted.

---

---
url: /data-loaders/nested-loaders.md
---
# Nested loaders

Sometimes, requests depend on other fetched data (e.g. fetching additional user information). For these scenarios, we can simply import the other loaders and use them **within a different loader**:

Call **and `await`** the loader inside the one that needs it, it will only be fetched once no matter how many times it is called during a navigation:

```ts twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
// ---cut---
// import the loader for user information
import { useUserData } from './loaders/users'
import { getCommonFriends, getCurrentUser } from './api'

export const useUserCommonFriends = defineBasicLoader(async (route) => {
  // loaders must be awaited inside other loaders
  // .        ⤵
  const user = await useUserData()

  // fetch other data
  const me = await getCurrentUser()
  const commonFriends = await getCommonFriends(me.id, user.id)
  return { ...user, commonFriends }
})
```

You will notice here that we have two different usages for `useUserData()`:

* One that returns all the necessary information we need *synchronously* (not used here). This is the composable that we use in components
* A second version that **only returns a promise of the data**. This is the version used within data loaders that enables sequential fetching.

## Nested invalidation

Since `useUserCommonFriends()` loader calls `useUserData()`, if `useUserData()` is somehow *invalidated*, it will also automatically invalidate `useUserCommonFriends()`. This depends on the implementation of the loader and is not a requirement of the API.

::: warning
Two loaders cannot use each other as that would create a *dead lock*.
:::

This can get complex with multiple pages exposing the same loader and other pages using some of their *already exported* loaders within other loaders. But it's not an issue, **the user shouldn't need to handle anything differently**, loaders are still only called once:

```ts twoslash
import 'unplugin-vue-router/client'
import './typed-router.d'
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
// ---cut---
import {
  getFriends,
  getCommonFriends,
  getUserById,
  getCurrentUser,
} from './api'

export const useUserData = defineBasicLoader('/users/[id]', async (route) => {
  return getUserById(route.params.id)
})

export const useCurrentUserData = defineBasicLoader(
  '/users/[id]',
  async (route) => {
    const me = await getCurrentUser()
    // imagine legacy APIs that cannot be grouped into one single fetch
    const friends = await getFriends(me.id)

    return { ...me, friends }
  }
)

export const useUserCommonFriends = defineBasicLoader(
  '/users/[id]',
  async (route) => {
    const user = await useUserData()
    const me = await useCurrentUserData()

    const friends = await getCommonFriends(user.id, me.id)
    return { ...me, commonFriends: { with: user, friends } }
  }
)
```

In the example above we are exporting multiple loaders but we don't need to care about the order in which they are called nor try optimizing them because **they are only called once and share the data**.

::: danger
**Caveat**: must call **and await** all nested loaders at the top of the parent loader (see `useUserData()` and `useCurrentUserData()`). You cannot put a different regular `await` in between. If you really need to await **anything that isn't a loader** in between, wrap the promise with `withDataContext()` to ensure the loader context is properly restored:

```ts{3}
export const useUserCommonFriends = defineBasicLoader(async (route) => {
  const user = await useUserData()
  await withContext(functionThatReturnsAPromise())
  const me = await useCurrentUserData()

  // ...
})
```

This allows nested loaders to be aware of their *parent loader*. This could probably be linted with an eslint plugin. It is similar to the problem `<script setup>` had before introducing the automatic `withAsyncContext()`. The same feature could be introduced (via a vite plugin) but will also have a performance cost. In the future, this *should* be solved with the [async-context](https://github.com/tc39/proposal-async-context) proposal (stage 2).
:::

---

---
url: /data-loaders/nuxt.md
---
# Nuxt

To use Data Loaders in Nuxt, create a new plugin file in the `plugins` directory of your Nuxt project and setup the Data Loaders plugin like usual:

```ts
// plugins/data-loaders.ts
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders'

export default defineNuxtPlugin({
  name: 'data-loaders',
  dependsOn: ['nuxt:router'],
  setup(nuxtApp) {
    const appConfig = useAppConfig()

    nuxtApp.vueApp.use(DataLoaderPlugin, {
      router: nuxtApp.vueApp.config.globalProperties.$router,
      isSSR: import.meta.server,
      // other options...
    })
  },
})
```

The two required options are:

* `router`: the Vue Router instance
* `isSSR`: a boolean indicating if the app is running on the server side

## No module?

> "Why do I need to write the plugin myself instead of using a Module?"

The Data Loader plugin has options that are not serializable (e.g. `selectNavigationResult()` and `errors`). In order to support those within a module, we would have to pass them through the `app.config.ts`, splitting up the configuration and making it harder to maintain. A short plugin is easier to understand and closer to the *vanilla* version.

---

---
url: /nuxt/getting-started.md
---
# Nuxt

Currently, this plugin is included as an experimental setting in Nuxt. You can enable it by adding the following to your `nuxt.config.ts`:

```ts{2-4}
export default defineNuxtConfig({
  experimental: {
    typedPages: true,
  },
})
```

The `sfc-typed-router` Volar plugin, that automatically types `useRoute()` and `$route` in page components, cannot be enabled using a feature flag in Nuxt at this time. Read how to enable it here: [Using the `sfc-typed-router` Volar plugin](/guide/typescript#using-the-sfc-typed-router-volar-plugin).

---

---
url: /data-loaders/reloading-data.md
---
# Reloading data

Very often, it is required to reload the data (e.g. fetch the latest data) without navigating. Since Vue Router considers that a duplicated navigation, we cannot just `router.push()` and expect navigation guards to run again to fetch the latest data. To overcome this, data loaders expose a convenient `reload` method that can be invoked to manually rerun the loader **without navigating**. This has some extra implications we will cover in this page.

## Navigation Unaware

When reloading data, the navigation is not involved, so not only the navigation guards will not run (`beforeRouteUpdate`, `beforeRouteLeave`, etc) but also any `NavigationResult` returned or thrown by the data loader will be ignored.

## Errors

Because we are not within a navigation, errors are actually kept in the `error` property of the loader. Similar to lazy loaders. This allows to display any errors that might have occurred during the reload.

---

---
url: /data-loaders/ssr.md
---
# Server side rendering

WIP

---

---
url: /guide/typescript.md
---
# Typed Routes

This plugin generates a `d.ts` file with all the typing overrides when the dev or build server is ran. Make sure to include it in your `tsconfig.json`'s (or `jsconfig.json`'s) `include` or `files` property:

```js
{
  // ...
  "include": [
    /* ... */
    "./typed-router.d.ts",
  ]
  // ...
}
```

The generated *Route Map* is picked up by `unplugin-vue-router/client` types and configures the `vue-router` types to be aware of the routes in your application. Making everything type safe!

::: tip
You can commit the newly added `.d.ts` files to your repository to make your life easier.
:::

```ts twoslash
// ---cut-start---
import 'unplugin-vue-router/client'
import './typed-router.d'
// ---cut-end---
// @moduleResolution: bundler
import { useRouter, useRoute } from 'vue-router'
const router = useRouter()
router.push('')
//           ^|
```

## Extra types

### `typed-router.d.ts` contents

You can always take a look at the generated `typed-router.d.ts` file to inspect what are the generated types. `unplugin-vue-router` creates and exports a couple of types, among them, `RouteNamedMap` with all the route records, typed, in your application. Each route record contains the route's name, path, typed params and a list of its child route names.

Other types, prefixed with an underscore (`_`), are used internally, e.g. `_RouteFileInfoMap` by the [`sfc-typed-router` Volar plugin](#using-the-sfc-typed-router-volar-plugin) to enhance typings for `useRoute()` and `$route`, if enabled, and **are not meant to be used directly**.

### Manually typing dynamically added routes

The `RouteNamedMap` interface contains all the routes in your application along with their metadata. You can augment it to add types for **dynamic routes** that are added during runtime.

```ts
import type { RouteNamedMap } from 'vue-router/auto-routes'
```

Note that, if you are using the [`sfc-typed-router` Volar plugin](#using-the-sfc-typed-router-volar-plugin), you should also augment the `_RouteFileInfoMap` interface for every dynamically added route corresponding to a page component.

```ts
export {} // needed in .d.ts files

declare module 'vue-router/auto-routes' {
  import type {
    RouteRecordInfo,
    ParamValue,
    // these are other param helper types
    ParamValueOneOrMore,
    ParamValueZeroOrMore,
    ParamValueZeroOrOne,
  } from 'vue-router'

  export interface RouteNamedMap {
    // the key is the name and should match the first generic of RouteRecordInfo
    'custom-dynamic-name': RouteRecordInfo<
      'custom-dynamic-name',
      '/added-during-runtime/[...path]',
      // these are the raw param types (accept numbers, strings, booleans, etc)
      { path: ParamValue<true> },
      // these are the normalized params as found in useRoute().params
      { path: ParamValue<false> },
      // this is a union of all children route names
      // if the route does not have nested routes, pass `never` or omit this generic entirely
      'custom-dynamic-child-name'
    >
    'custom-dynamic-child-name': RouteRecordInfo<
      'custom-dynamic-child-name',
      '/added-during-runtime/[...path]/child',
      { path: ParamValue<true> },
      { path: ParamValue<false> },
      never
    >
  }

  export interface _RouteFileInfoMap {
    // the key is the file path and should match the page component's file path
    '/added-during-runtime/[...path].vue': {
      // these are the route names that can be displayed within this component
      routes: 'custom-dynamic-name' | 'custom-dynamic-child-name'
      // these are the views that can be used in this file
      views: 'default'
    }

    '/added-during-runtime/[...path]/child.vue': {
      routes: 'custom-dynamic-child-name'
      views: never
    }
  }
}
```

You can now pass a *type param* to the generic route location types to narrow down the type of the route. This automatically includes any child routes typings as well:

```ts twoslash
// ---cut-start---
import 'unplugin-vue-router/client'
import './typed-router.d'
import { useRoute, type RouteLocationNormalizedLoaded } from 'vue-router'
// ---cut-end---
// @errors: 2322 2339
// @moduleResolution: bundler
// These are all valid ways to get a typed route and return the
// provided route's and any of its child routes' typings.
// Note that `/users/[id]/edit` is a child route
// of `/users/[id]` in this example.

// Not recommended, since this leaves out any child routes' typings.
const userRouteWithIdCasted =
  useRoute() as RouteLocationNormalizedLoaded<'/users/[id]'>
userRouteWithIdCasted.params.id

// Better way. Includes child routes' typings, but no autocompletion.
const userRouteWithIdTypeParam = useRoute<'/users/[id]'>()
userRouteWithIdTypeParam.params.id

// 👇 This one is the easiest to write because it both
//    autocompletes and includes child routes' typings.
const userRouteWithIdParam = useRoute('/users/[id]')
userRouteWithIdParam.name
userRouteWithIdParam.params.id
```

### Automatically typed `useRoute()`

The `sfc-typed-router` Volar plugin automatically types `useRoute()` and `$route` correctly in page components, so you don't have to write code like `useRoute('/users/[id]')`, allowing you to write less code.

To start using the plugin, add the following to the `tsconfig.json` file that includes your Vue files:

```json
{
  "compilerOptions": {
    // needed for the plugin to correctly resolve paths
    "rootDir": "."
    // ...
  },
  // ...
  "vueCompilerOptions": {
    "plugins": ["unplugin-vue-router/volar/sfc-typed-router"]
  }
}
```

As long as this plugin isn't enabled in Nuxt by default with `experimental.typedPages: true` or through any other experimental feature flag, you should manually add the plugin via `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  // ...
  typescript: {
    tsConfig: {
      vueCompilerOptions: {
        plugins: ['unplugin-vue-router/volar/sfc-typed-router'],
      },
    },
  },
})
```

When using the `sfc-typed-router` Volar plugin, `useRoute()` and `$route` are typed automatically for page components under the hood, so you don't have to do it manually.

---

---
url: /why.md
---
# Why?

This project idea came from trying [to type the router directly using Typescript](https://github.com/vuejs/router/pull/1397/commits/a7c591b6fd5d8478ba3f87e833514bc0e30f93a9), finding out it's not fast enough to be pleasant to use and, ending up using build-based tools, taking some inspiration from other projects like:

* [Nuxt](https://nuxtjs.org/) - The Vue.js Framework
* [vite-plugin-pages](https://github.com/hannoeru/vite-plugin-pages) - Framework agnostic file based routing
* [Typed Router for Nuxt](https://github.com/victorgarciaesgi/nuxt-typed-router) - A module to add typed routing to Nuxt

It's currently included as [an experimental setting in Nuxt](https://nuxt.com/docs/guide/going-further/experimental-features#typedpages).