Uso

As páginas são componentes Vue e podem ter qualquer extensão válida que o Nuxt suporta (por padrão .vue, .js, .jsx, .mjs, .ts ou .tsx).

O Nuxt criará automaticamente uma rota para cada página no seu diretório ~/pages/.

<template>
  <h1>Página de índice</h1>
</template>

O arquivo pages/index.vue será mapeado para a rota / da sua aplicação.

Se você estiver usando app.vue, certifique-se de usar o componente <NuxtPage/> para exibir a página atual:

<template>
  <div>
    <!-- Marcação compartilhada entre todas as páginas, ex: NavBar -->
    <NuxtPage />
  </div>
</template>

As páginas devem ter um único elemento raiz para permitir transições de rota entre páginas. Comentários HTML também são considerados elementos.

Isso significa que quando a rota é renderizada no servidor, ou gerada estaticamente, você poderá ver seu conteúdo corretamente, mas quando você navega para essa rota durante a navegação no lado do cliente, a transição entre rotas falhará e você verá que a rota não será renderizada.

Aqui estão alguns exemplos para ilustrar como uma página com um único elemento raiz se parece:

<template>
  <div>
    <!-- Esta página tem corretamente apenas um único elemento raiz -->
    Conteúdo da página
  </div>
</template>

Rotas Dinâmicas

Se você colocar qualquer coisa entre colchetes, ela será transformada em um parâmetro de rota dinâmica. Você pode misturar e combinar vários parâmetros e até mesmo texto não dinâmico dentro de um nome de arquivo ou diretório.

Se você quiser que um parâmetro seja opcional, você deve colocá-lo entre colchetes duplos - por exemplo, ~/pages/[[slug]]/index.vue ou ~/pages/[[slug]].vue corresponderá tanto a / quanto a /teste.

-| pages/
---| index.vue
---| users-[group]/
-----| [id].vue

Dado o exemplo acima, você pode acessar group/id dentro do seu componente via o objeto $route:

<template>
  <p>{{ $route.params.group }} - {{ $route.params.id }}</p>
</template>

Navegar para /users-admins/123 renderizaria:

<p>admins - 123</p>

Se você quiser acessar a rota usando a API de Composição, há uma função global useRoute que permitirá acessar a rota assim como this.$route na API de Opções.

const route = useRoute()

if (route.params.group === 'admins' && !route.params.id) {
  console.log('Aviso! Certifique-se de que o usuário está autenticado!')
}

Rota Catch-all

Se você precisar de uma rota catch-all, você a cria usando um arquivo nomeado como [...slug].vue. Isso corresponderá a todas as rotas sob esse caminho.

<template>
  <p>{{ $route.params.slug }}</p>
</template>

Navegar para /hello/world renderizaria:

<p>["hello", "world"]</p>

Rotas Aninhadas

É possível exibir rotas aninhadas com <NuxtPage>.

Exemplo:

-| pages/
---| parent/
-----| child.vue
---| parent.vue

Esta árvore de arquivos gerará estas rotas:

[
  {
    path: '/parent',
    component: '~/pages/parent.vue',
    name: 'parent',
    children: [
      {
        path: 'child',
        component: '~/pages/parent/child.vue',
        name: 'parent-child'
      }
    ]
  }
]

Para exibir o componente child.vue, você deve inserir o componente <NuxtPage> dentro de pages/parent.vue:

<template>
  <div>
    <h1>Eu sou a visão pai</h1>
    <NuxtPage :foobar="123" />
  </div>
</template>

const props = defineProps(['foobar'])

console.log(props.foobar)

Chaves de Rotas Filhas

Se você quiser mais controle sobre quando o componente <NuxtPage> é re-renderizado (por exemplo, para transições), você pode passar uma string ou função via a prop pageKey, ou você pode definir um valor key via definePageMeta:

<template>
  <div>
    <h1>Eu sou a visão pai</h1>
    <NuxtPage :page-key="route => route.fullPath" />
  </div>
</template>

Ou alternativamente:

definePageMeta({
  key: route => route.fullPath
})

Grupos de Rotas

Em alguns casos, você pode querer agrupar um conjunto de rotas de uma maneira que não afete o roteamento baseado em arquivos. Para isso, você pode colocar arquivos em uma pasta que está envolvida em parênteses - ( e ).

Por exemplo:

-| pages/
---| index.vue
---| (marketing)/
-----| about.vue
-----| contact.vue

Isso produzirá páginas /, /about e /contact em seu aplicativo. O grupo marketing é ignorado para fins de estrutura de URL.

Metadados da Página

Você pode querer definir metadados para cada rota em seu aplicativo. Você pode fazer isso usando o macro definePageMeta, que funcionará tanto em <script> quanto em <script setup>:

definePageMeta({
  title: 'Minha página inicial'
})

Esses dados podem então ser acessados em todo o resto do seu aplicativo a partir do objeto route.meta.

const route = useRoute()

console.log(route.meta.title) // Minha página inicial

Se você estiver usando rotas aninhadas, os metadados da página de todas essas rotas serão mesclados em um único objeto. Para mais informações sobre metadados de rota, veja os documentos do vue-router.

Assim como defineEmits ou defineProps (veja documentos do Vue), definePageMeta é um macro de compilador. Ele será compilado, então você não pode referenciá-lo dentro do seu componente. Em vez disso, os metadados passados para ele serão elevados para fora do componente. Portanto, o objeto de metadados da página não pode referenciar o componente. No entanto, ele pode referenciar ligações importadas, bem como funções puras definidas localmente.

import { someData } from '~/utils/example'

function validateIdParam(route) {
  return route.params.id && !isNaN(Number(route.params.id))
}

const title = ref('')

definePageMeta({
  validate: validateIdParam,
  someData,
  title,    // não faça isso, o ref será elevado para fora do componente
})

Metadados Especiais

Claro, você pode definir metadados para seu próprio uso em todo o seu aplicativo. Mas alguns metadados definidos com definePageMeta têm um propósito particular:

alias

Você pode definir aliases de página. Eles permitem acessar a mesma página a partir de diferentes caminhos. Pode ser uma string ou um array de strings conforme definido na documentação do vue-router.

keepalive

O Nuxt envolverá automaticamente sua página no componente Vue <KeepAlive> se você definir keepalive: true em seu definePageMeta. Isso pode ser útil, por exemplo, em uma rota pai que tem rotas filhas dinâmicas, se você quiser preservar o estado da página entre mudanças de rota.

Quando seu objetivo é preservar o estado para rotas pai, use esta sintaxe: <NuxtPage keepalive />. Você também pode definir props para serem passadas para <KeepAlive> (veja uma lista completa).

Você pode definir um valor padrão para esta propriedade em seu nuxt.config.

key

Veja acima.

layout

Você pode definir o layout usado para renderizar a rota. Isso pode ser falso (para desativar qualquer layout), uma string ou um ref/computed, se você quiser torná-lo reativo de alguma forma. Mais sobre layouts.

layoutTransition e pageTransition

Você pode definir propriedades de transição para o componente <transition> que envolve suas páginas e layouts, ou passar false para desativar o invólucro <transition> para essa rota. Você pode ver uma lista de opções que podem ser passadas ou ler mais sobre como as transições funcionam.

Você pode definir valores padrão para essas propriedades em seu nuxt.config.

middleware

Você pode definir middleware para aplicar antes de carregar esta página. Ele será mesclado com todos os outros middlewares usados em qualquer rota pai/filha correspondente. Pode ser uma string, uma função (uma função middleware anônima/in-line seguindo o padrão de guarda global antes), ou um array de strings/funções. Mais sobre middleware nomeado.

name

Você pode definir um nome para a rota desta página.

path

Você pode definir um matcher de caminho, se tiver um padrão mais complexo do que pode ser expresso com o nome do arquivo. Veja os documentos do vue-router para mais informações.

props

Permite acessar os params da rota como props passadas para o componente da página. Veja os documentos do vue-router para mais informações.

Tipagem de Metadados Personalizados

Se você adicionar metadados personalizados para suas páginas, pode querer fazê-lo de uma maneira segura em termos de tipo. É possível aumentar o tipo do objeto aceito por definePageMeta:

declare module '#app' {
  interface PageMeta {
    pageType?: string
  }
}

// É sempre importante garantir que você importe/exporte algo ao aumentar um tipo
export {}

Navegação

Para navegar entre as páginas do seu aplicativo, você deve usar o componente <NuxtLink>.

Este componente está incluído no Nuxt e, portanto, você não precisa importá-lo como faz com outros componentes.

Um link simples para a página index.vue na sua pasta pages:

<template>
  <NuxtLink to="/">Página inicial</NuxtLink>
</template>

Navegação Programática

O Nuxt permite navegação programática através do método utilitário navigateTo(). Usando este método utilitário, você poderá navegar programaticamente o usuário em seu aplicativo. Isso é ótimo para receber entrada do usuário e navegá-lo dinamicamente por toda a sua aplicação. Neste exemplo, temos um método simples chamado navigate() que é chamado quando o usuário envia um formulário de pesquisa.

const name = ref('');
const type = ref(1);

function navigate(){
  return navigateTo({
    path: '/search',
    query: {
      name: name.value,
      type: type.value
    }
  })
}

Páginas Apenas para Cliente

Você pode definir uma página como apenas para cliente dando a ela um sufixo .client.vue. Nenhum conteúdo desta página será renderizado no servidor.

Páginas Apenas para Servidor

Você pode definir uma página como apenas para servidor dando a ela um sufixo .server.vue. Embora você possa navegar para a página usando navegação no lado do cliente, controlada pelo vue-router, ela será renderizada automaticamente com um componente de servidor, o que significa que o código necessário para renderizar a página não estará no seu pacote do lado do cliente.

Roteamento Personalizado

À medida que sua aplicação cresce e se torna mais complexa, seu roteamento pode exigir mais flexibilidade. Por esse motivo, o Nuxt expõe diretamente o roteador, as rotas e as opções do roteador para personalização de diferentes maneiras.

Múltiplos Diretórios de Páginas

Por padrão, todas as suas páginas devem estar em um diretório pages na raiz do seu projeto.

No entanto, você pode usar Camadas do Nuxt para criar agrupamentos das páginas do seu aplicativo:

-| some-app/
---| nuxt.config.ts
---| pages/
-----| app-page.vue
-| nuxt.config.ts

// some-app/nuxt.config.ts
export default defineNuxtConfig({
})

export default defineNuxtConfig({
  extends: ['./some-app'],
})