Routing 🛣

provides file-based routing, powered by @islands/pages

As you add files to the src/pages directory, they will become available as routes based on their filename, and Vue Router will be configured automatically.

Basic Routing

Each page file corresponds to a route with the same name:

• src/pages/about.vue -> /about
• src/pages/introduction.mdx -> /introduction
• src/pages/users/profile.vue -> /users/profile

Index Routes

Files with the name index are treated as the index page of a route:

• src/pages/index.vue -> /
• src/pages/users/index.vue -> /users

Aliased Routes

If you want the same component to be rendered as different pages, you can use Vue Router's alias in frontmatter:

<page>
alias: ['/posts']
</page>

Override Routes

You can also override the default structure by providing path in frontmatter:

---
path: /guide/intro
---

Pretty URLs by Default

If you prefer explicit .html paths, such as /guide/intro.html, disable prettyUrls.

Page Hooks 🎣

You can customize all pages using the extendFrontmatter and extendRoute hooks.

Dynamic Routes

supports dynamic parameters in the filename, so that one page can be used to generate many different paths based on custom logic.

Pages with dynamic parameters must define getStaticPaths.

Named Parameters

Named parameters are denoted using square brackets:

• src/pages/posts/[slug].vue -> /posts/:slug, example: /posts/introduction

Rest Parameters

Catch-all routes are denoted with square brackets containing an ellipsis:

• src/pages/[...all].vue -> /:all(.*)*, example: /a/dynamic/path

The text after the ellipsis will be used both to name the route, and as the name of the prop in which the route parameters are passed.

Generating Dynamic Routes

Pages with dynamic parameters must provide a getStaticPaths function, which specifies the paths that should be generated at build time.

It must return an array of objects, where each object specifies:

• params: the parameters to interpolate in the path
• props: optional, any data needed to render the page

<script lang="ts">
import { fetchArticles } from '~/logic/articles'

export default definePageComponent({
  async getStaticPaths () {
    const articles = await fetchArticles()

    return articles.map(article => ({
      // Specify the parameters for the page.
      params: { id: String(article.id) },

      // Pass any data needed to render the page.
      props: { article },
    }))
  },
})
</script>

<script setup lang="ts">
import { Article } from '~/logic/articles'

defineProps<{ article: Article }>()
</script>

<template>
  <p>{{ article.title }}</p>
</template>

src/pages/articles/[id].vue

params

The params of each path object will be used to resolve any named and rest parameters in the page filename, similar to how you would provide named parameters when using Vue Router.

You can access them in the page component using $route.params, or by specifying them in defineProps.

props

You can pass additional data to each generated page by using props in each path object, and they will be provided as Vue props in the page component.

You can access them using defineProps as in the example above, or as props in usePage if you need to access them in a parent layout.

Common Gotchas

getStaticPaths must be specified inside the default export of a Vue component.

Use definePageComponent to provide intellisense, it will be automatically imported.

Using External Data

getStaticPaths can be async you can generate paths using data from an API or CMS.

See this example that generates pages for articles obtained using a Directus API.

More Demos

See examples of dynamic paths in this site: one and two, and the source code.

See a pagination demo in a blog, and the source code.