definePageMeta

definePageMeta is a compile-time macro that attaches metadata to a page. Nuxt reads that metadata to pick a layout, run middleware, gate the route, and animate the transition.

The Macro

<!-- pages/login.vue -->
<script setup lang="ts">
definePageMeta({
  layout: 'auth',
  middleware: 'guest',
  pageTransition: { name: 'fade', mode: 'out-in' },
})
</script>

<template>
  <form>...</form>
</template>

The macro is processed by the Nuxt build, so it must appear at the top level of <script setup> and its arguments must be statically analyzable (no imports of variables to use here).

Common Keys

A few keys carry most of the weight:

• layout — name of a file in layouts, or false to disable.
• middleware — name, array of names, or inline function.
• validate — gate the route by params or query.
• pageTransition / layoutTransition — Vue <Transition> options.
• keepalive — cache the component when navigating away.
• alias — extra paths that should match this page.

definePageMeta({
  alias: ['/sign-in'],
  keepalive: { max: 5 },
  pageTransition: { name: 'slide', mode: 'out-in' },
})

Reading Meta at Runtime

You can read a page’s meta back from anywhere in your app via useRoute():

const route = useRoute()
const layout = route.meta.layout
const transition = route.meta.pageTransition

This is helpful in layouts that want to react to per-page settings — for example, hiding a sidebar based on a route.meta.sidebar flag the page sets.

A Note on Where It Goes

definePageMeta is page-only. It does not work in app.vue, layouts, components, or composables — Nuxt would have no page to attach the meta to. Keep it inside a file under pages/.