pages directory is optional
The pages directory is optional. If you only use app.vue, vue-router will not be included. To force the pages system, set pages: true in nuxt.config or have a router.options.ts file.
components: navigation & structure
26 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Page file extensions supported
Pages are Vue components and can have any valid extension that Nuxt supports. By default, the supported extensions are .vue, .js, .jsx, .mjs, .ts, and .tsx.
Pages directory automatic routing
Nuxt automatically creates a route for every page in the ~/pages/ directory. The app/pages/index.vue file will be mapped to the / route of the application.
Pages must have single root element
Pages must have a single root element to allow route transitions between pages. HTML comments are considered elements as well. When the route is server-rendered or statically generated, a page without a single root element will not render correctly during client-side navigation.
Dynamic route parameters with square brackets
Placing anything within square brackets in a filename will turn it into a dynamic route parameter. For example, ~/pages/users-[group]/[id].vue creates dynamic parameters that can be accessed via the $route object as route.params.group and route.params.id.
Optional dynamic route parameters with double square brackets
To make a dynamic route parameter optional, enclose it in double square brackets. For example, ~/pages/[[slug]]/index.vue or ~/pages/[[slug]].vue will match both / and /test.
Named parent routes take priority over nested dynamic routes
For nested routing, named parent routes will take priority over nested dynamic routes. For the /foo/hello route, ~/pages/foo.vue will take priority over ~/pages/foo/[slug].vue. Use ~/pages/foo/index.vue and ~/pages/foo/[slug].vue to match /foo and /foo/hello with different pages.
Catch-all route with [...slug] syntax
A catch-all route can be created using a file named [...slug].vue. This will match all routes under that path. For example, navigating to /hello/world with a catch-all route will render $route.params.slug as ["hello", "world"].
definePageMeta key for child route re-render control
You can define a key value via definePageMeta in a child page component to control when the page is re-rendered. For example: definePageMeta({ key: route => route.fullPath }). This provides an alternative to the pageKey prop on <NuxtPage>.
Route groups with parentheses syntax
Routes can be grouped in a way that does not affect file-based routing by putting files in a folder wrapped in parentheses. For example, (marketing)/about.vue produces /about without the marketing prefix in the URL. The group name is ignored for URL structure purposes.
Accessing route groups via route.meta.groups (v4.3+)
Route groups are automatically available in the route metadata as route.meta.groups. This allows you to access the group information in your components for conditional logic, styling, or other purposes. For example, route.meta.groups?.includes('marketing') can be used to check if a page belongs to a group.
definePageMeta macro for page metadata
The definePageMeta macro allows you to define metadata for each route. It works in both <script> and <script setup> blocks. This data can be accessed throughout the app from the route.meta object. definePageMeta is a compiler macro that is compiled away and cannot be referenced within the component; metadata is hoisted out of the component.
definePageMeta restrictions on reactive data
The definePageMeta macro cannot reference any reactive data or functions that cause side effects, as this can lead to unexpected behavior. Page meta object cannot reference the component but can reference imported bindings and locally defined pure functions.
definePageMeta special metadata: alias
The alias metadata property in definePageMeta allows you to define page aliases. They allow you to access the same page from different paths. It can be either a string or an array of strings as defined in the vue-router documentation.
definePageMeta special metadata: keepalive
The keepalive metadata property in definePageMeta can be set to true to automatically wrap your page in the Vue <KeepAlive> component. This is useful in parent routes with dynamic child routes to preserve page state across route changes. Alternatively, use <NuxtPage keepalive /> syntax in the parent. Props can be passed to <KeepAlive> via this property.
definePageMeta special metadata: layout
The layout metadata property in definePageMeta defines the layout used to render the route. It can be false (to disable any layout), a string, or a ref/computed to make it reactive.
definePageMeta special metadata: layoutTransition and pageTransition
The layoutTransition and pageTransition metadata properties in definePageMeta define transition properties for the <transition> component that wraps pages and layouts. You can pass options compatible with Vue's <transition> component or pass false to disable the transition wrapper for that route.
definePageMeta special metadata: middleware
The middleware metadata property in definePageMeta allows you to define middleware to apply before loading the page. It will be merged with all other middleware used in matching parent/child routes. It can be a string, a function (an anonymous/inlined middleware function), or an array of strings/functions.
definePageMeta special metadata: name
The name metadata property in definePageMeta allows you to define a name for the page's route.
definePageMeta special metadata: path
The path metadata property in definePageMeta allows you to define a path matcher for more complex patterns than can be expressed with the filename. See vue-router docs for information on custom regex in params.
definePageMeta special metadata: props
The props metadata property in definePageMeta allows accessing the route params as props passed to the page component. See vue-router docs for more information.
Typing custom metadata with PageMeta interface augmentation
You can augment the type of the object accepted by definePageMeta by declaring a module augmentation in an index.d.ts file: declare module '#app' { interface PageMeta { pageType?: string } }. This allows type-safe custom metadata for pages.
Client-only pages with .client.vue suffix
You can define a page as client only by giving it a .client.vue suffix. None of the content of this page will be rendered on the server.
Server-only pages with .server.vue suffix
You can define a page as server only by giving it a .server.vue suffix. While you can navigate to the page using client-side navigation controlled by vue-router, it will be rendered with a server component automatically, meaning the code required to render the page will not be in your client-side bundle. Server-only pages must have a single root element.
Multiple pages directories with Nuxt Layers
By default, all pages should be in one app/pages directory at the root of the project. However, you can use Nuxt Layers to create groupings of your app's pages by having multiple projects with their own pages directories and using the extends property in nuxt.config.
Pages prerendering requirements
Pages are only automatically registered for prerendering if you have not disabled nitro.prerender.crawlLinks and you have at least one page in your nitro.prerender.routes list.