Ir para o conteúdo
Promovaweb

App Router e layouts do Next.js

StayCloudVPS Agêntica

O mesmo ambiente do SetupVibe, agora numa VPS

Os atalhos, o shell e as CLIs de IA que você já usa no computador rodam numa VPS da StayCloud com servidor no Brasil.

Criar minha VPS na StayCloud

Link de parceiro da Promovaweb.

Black Friday até 30/11

30%off

nos 2 primeiros meses do plano mensal da VPS

  • Backup diário grátis para sempre
  • Servidores em São Paulo no datacenter da Ascenty
  • Datacenter Tier III manutenção sem parada
  • Acesso root com disco SSD NVMe
  • Réplica do backup em Ashburn, nos EUA

O App Router associa pastas a segmentos do endereço de uma aplicação Next.js. Você define páginas e layouts com arquivos dentro da pasta app.

Sumário da página

  1. A pasta participa do endereço
  2. Layouts compartilham a estrutura visual
  3. Segmentos dinâmicos identificam registros
  4. Navegação e estados de espera
  5. Organização não substitui autorização

A pasta participa do endereço

O App Router é o sistema de roteamento do Next.js organizado pela pasta app. Cada pasta pode representar um segmento da URL. O arquivo page define o conteúdo público daquele endereço. Uma pasta isolada, sem a página ou outro arquivo de rota apropriado, não se transforma automaticamente numa tela disponível para visita.

Num catálogo, a seção de produtos pode reunir a listagem e as páginas individuais. A listagem apresenta os itens disponíveis. Um segmento dinâmico identifica qual produto será consultado. Você mantém uma estrutura de componentes para diferentes registros, enquanto o endereço fornece o identificador necessário para buscar o produto correto.

Essa relação entre arquivos e endereços torna a navegação parte da organização do projeto. Ela também exige cuidado com nomes, páginas ausentes e conteúdo indisponível. Um endereço bem formado pode apontar para um produto removido. A aplicação precisa responder de acordo com a existência do registro e com a permissão de acesso àquele conteúdo.

Layouts compartilham a estrutura visual

Um layout envolve páginas e outros layouts. No painel de uma loja, ele pode conter o menu lateral e a área principal. Quando você navega de produtos para compras, a estrutura compartilhada permanece. A documentação descreve a preservação de estado e de interatividade dos layouts durante essa navegação, evitando reconstruir toda a apresentação a cada troca.

O layout raiz define as tags html e body. Layouts internos acrescentam estruturas específicas de uma seção. Você pode ter uma apresentação pública para o catálogo e outra para o painel administrativo. O arquivo de layout recebe o conteúdo filho e o posiciona dentro da composição, mantendo as convenções do framework.

Essa divisão mantém o JavaScript de interatividade restrito às partes da interface que precisam dele. Um layout é um Server Component por padrão. Componentes que precisam de estado ou eventos podem ser inseridos como partes interativas da estrutura. O local dessa divisão afeta o conjunto de módulos enviado ao navegador e merece ser lido junto com a árvore de componentes.

  1. Layout raiz

    Define a estrutura geral do documento.

  2. Layout de produtos

    Compartilha a navegação da seção.

  3. Página do produto

    Mostra o registro correspondente ao endereço.

Layouts se encaixam e envolvem o conteúdo da página identificada pela rota.

Segmentos dinâmicos identificam registros

Um segmento entre colchetes representa uma parte variável do endereço. A página recebe os parâmetros da rota e usa esses valores para localizar o conteúdo. O mesmo componente pode apresentar vários produtos, desde que cada identificador corresponda a um registro disponível. A consulta que lê o registro confere a sessão e a permissão sobre o produto solicitado.

Parâmetros de busca representam outra parte do endereço. Você pode usá-los para paginação, ordenação ou filtros. Ler informações que só existem na requisição afeta a forma de renderização. A documentação distingue o uso desses parâmetros na página do uso em componentes interativos que apenas reorganizam uma lista já recebida.

A forma de acessar parâmetros mudou ao longo das versões do framework. A referência atual apresenta APIs assíncronas em pontos do App Router. Para interpretar uma aplicação antiga, confira a versão instalada e o guia correspondente. Copiar uma assinatura de função de outra versão pode produzir erro mesmo quando os nomes dos arquivos parecem corretos.

O componente Link participa da navegação entre rotas e pode carregar conteúdo antes do clique. Assim, parte da próxima página já pode estar disponível quando você clica no link. O comportamento varia com o tipo de rota e com a informação disponível antes da visita. Uma página personalizada ainda pode exigir uma requisição para completar a resposta.

O arquivo loading descreve uma interface de espera para um segmento. A estrutura de espera aparece enquanto o conteúdo correspondente é preparado. Isso é particularmente útil numa página de compras que consulta um serviço externo. A espera precisa deixar claro qual conteúdo ainda está sendo buscado, sem apresentar valores fictícios como se fossem resultados.

Arquivos de erro e de conteúdo ausente tratam outras condições da navegação. Uma consulta que falhou é diferente de um produto que não existe. O projeto deve representar essas situações de forma coerente para você e para a resposta HTTP. O streaming acrescenta cuidados porque os cabeçalhos podem já ter sido enviados quando uma falha aparece.

Organização não substitui autorização

Uma pasta administrativa reúne os arquivos das páginas do painel. A sessão é conferida na operação que consulta ou altera o registro, inclusive quando a chamada chega direto ao endpoint. A mesma exigência vale para Server Actions e Route Handlers, mesmo quando só existe um botão visível dentro do painel.

O App Router oferece convenções de composição, mas não conhece as permissões comerciais da sua loja. Você define quais perfis podem editar preços, quais compras pertencem a cada cliente e quais informações podem ser públicas. Essas verificações pertencem à aplicação e precisam continuar válidas numa chamada direta, sem passar pela interface.

O próximo assunto é a divisão entre Server Components e Client Components. Ela complementa o roteamento: a pasta identifica a página, enquanto a árvore de componentes distribui o trabalho entre servidor e navegador.