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
---

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.

getStaticPaths

Pages with dynamic params must provide a getStaticPaths function.

getStaticPaths should return an array of objects to determine which paths should be statically generated at build time.

It must be specified in the default export of a Vue component, you may use the definePageComponent helper to provide intellisense, it will be automatically imported.

<script lang="ts">
export default definePageComponent({
  getStaticPaths () {
    return [
      { params: { section: 'one' }, props: { message: '...' } },
      { params: { section: 'two' }, props: { message: '...' } },
    ]
  ],
})
</script>

<script setup lang="ts">
defineProps<{ message: string }>()
</script>

<template>
  <p>{{ message }}</p>
</template>

src/pages/dynamic/[section].vue

Demos

See the generated examples: one and two, and the source code.

See a pagination demo, and the source code.

params

The params key of each path 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 props in the page component.

You can access them using defineProps as in the example above, or as props in usePage.