Habilidade: Mergulho Profundo em Roteamento Next.js - Uma receita de habilidade Claude Code para padrões avançados de roteamento do App Router

Estas receitas de habilidade são projetadas para Claude Code, mas também funcionam com outros agentes de codificação de IA que suportam arquivos de habilidade/instrução.

Receita

O conteúdo completo do SKILL.md que você pode copiar para .claude/skills/nextjs-routing/SKILL.md:

---
name: nextjs-routing-deep-dive
description: "Padrões avançados de roteamento do App Router, rotas paralelas, rotas de interceptação e layouts. Use quando solicitado: ajuda com roteamento, rotas paralelas, rotas de interceptação, padrão de modal, grupos de rotas, rotas dinâmicas, middleware, rotas catch-all."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Agent"
---
 
# Mergulho Profundo em Roteamento Next.js
 
Você é um especialista em roteamento do Next.js App Router. Forneça orientação autoritativa sobre todos os padrões de roteamento disponíveis no App Router.
 
## Convenções de Arquivos
 
| Arquivo | Propósito | Renderiza |
|------|---------|---------|
| layout.tsx | Wrapper de UI compartilhado, preserva estado na navegação | Envolve os filhos |
| template.tsx | Semelhante ao layout, mas remonta a cada navegação | Envolve os filhos |
| page.tsx | UI única da rota, torna a rota publicamente acessível | Conteúdo da rota |
| loading.tsx | UI de carregamento instantânea via Suspense | Enquanto a página carrega |
| error.tsx | Limite de erro para o segmento | Em caso de erro |
| not-found.tsx | UI 404 para o segmento | Ao chamar notFound() |
| default.tsx | Fallback para slots de rota paralela quando não há correspondência | Fallback do slot |
| route.ts | Endpoint de API (GET, POST, etc.) | JSON ou Response |
| global-error.tsx | Limite de erro no nível raiz | Em caso de erro raiz |
 
## Tipos de Rotas
 
### Rotas Estáticas

app/about/page.tsx -> /about app/blog/page.tsx -> /blog app/dashboard/settings/page.tsx -> /dashboard/settings

### Rotas Dinâmicas

app/blog/[slug]/page.tsx -> /blog/meu-post (parâmetro único) app/shop/[...slug]/page.tsx -> /shop/a/b/c (catch-all, obrigatório) app/docs/[[...slug]]/page.tsx -> /docs ou /docs/a/b (catch-all opcional)

### Grupos de Rotas

app/(marketing)/about/page.tsx -> /about (sem /marketing na URL) app/(shop)/cart/page.tsx -> /cart app/(auth)/login/layout.tsx -> layout separado para páginas de autenticação

Grupos de rotas com parênteses NÃO afetam a URL. Use-os para:
- Organizar rotas por preocupação sem alterar a estrutura da URL
- Aplicar layouts diferentes a diferentes grupos de rotas
- Dividir o layout raiz em múltiplos layouts raiz

### Rotas Paralelas

app/@modal/default.tsx app/@modal/(.)photo/[id]/page.tsx app/layout.tsx -> recebe props { children, modal } app/photo/[id]/page.tsx -> destino de navegação manual

Regras para rotas paralelas:
- Definidas com a convenção @folder
- Cada slot é passado como uma prop para o layout pai
- Slots renderizam independentemente, podem ter seus próprios estados de loading/error
- SEMPRE crie um default.tsx para cada slot (evita 404 em atualizações manuais)
- Slots NÃO afetam a estrutura da URL

### Rotas de Interceptação

(.)folder -> intercepta no mesmo nível (..)folder -> intercepta um nível acima (..)(..)folder -> intercepta dois níveis acima (...)folder -> intercepta a partir da raiz

Padrão comum - interceptação de modal:

app/@modal/(.)photo/[id]/page.tsx -> navegação suave exibe modal app/photo/[id]/page.tsx -> navegação manual exibe página completa

## Árvore de Decisão: Escolhendo um Padrão de Roteamento

1. **Você precisa de um wrapper compartilhado que persista entre as navegações?**
   - Sim -> Use layout.tsx
   - Sim, mas ele precisa ser remontado -> Use template.tsx

2. **Você precisa de múltiplas seções independentes na mesma página?**
   - Sim -> Use rotas paralelas (@slot)
   - Cada seção carrega independentemente -> Adicione loading.tsx por slot

3. **Você precisa de um modal que abre em navegação suave, mas exibe uma página completa em navegação manual?**
   - Sim -> Use rotas de interceptação + rotas paralelas
   - Crie um slot @modal com rota de interceptação (.)

4. **Você precisa de layouts diferentes para seções diferentes?**
   - Sim -> Use grupos de rotas: (marketing), (dashboard), (auth)

5. **Você precisa de segmentos dinâmicos na URL?**
   - Parâmetro único -> [param]
   - Múltiplos segmentos -> [...params] ou [[...params]]

6. **Você precisa proteger rotas?**
   - Redirecionamentos simples -> middleware.ts
   - Lógica de autenticação complexa -> layout.tsx com verificação de autenticação
   - Proteção de API -> route.ts com validação de autenticação

## Middleware

```typescript
// middleware.ts (raiz do projeto ou src/)
import \{ NextResponse \} from "next/server";
import type \{ NextRequest \} from "next/server";

export function middleware(request: NextRequest) \{
  // Verifica autenticação
  const token = request.cookies.get("session");
  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) \{
    return NextResponse.redirect(new URL("/login", request.url));
  \}
  return NextResponse.next();
\}

export const config = \{
  // Corresponde a todas as rotas, exceto arquivos estáticos e API
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
\};

Regras do Middleware:

• Executa em TODAS as requisições correspondentes (mantenha-o rápido, abaixo de 200ms)
• Não pode acessar o banco de dados diretamente (limitações do Edge Runtime)
• Use para: redirecionamentos, reescritas, injeção de cabeçalhos, verificações de token de autenticação
• NÃO use para: busca de dados complexa, computação pesada

Anti-Padrões Comuns de Roteamento

1. Colocar lógica de API em page.tsx - Use route.ts para endpoints de API
2. Layouts profundamente aninhados que não podem ser escapados - Use grupos de rotas para sair
3. Falta de default.tsx em rotas paralelas - Causa 404 em atualizações manuais
4. Usar redirect() em renderização - Use em Server Components ou middleware, não em Client Components
5. Aninhamento excessivo de rotas - Mantenha as rotas com no máximo 3-4 níveis de profundidade; use grupos de rotas para organização
6. Roteamento do lado do cliente para autenticação - Prefira middleware para redirecionamentos de autenticação (executa antes da renderização)

Modelos de Estrutura de Arquivos

App de E-commerce

app/
  (shop)/
    layout.tsx           # Layout da loja com navegação
    page.tsx             # Página inicial
    products/
      page.tsx           # Listagem de produtos
      [slug]/page.tsx    # Detalhe do produto
    cart/page.tsx
    checkout/page.tsx
  (account)/
    layout.tsx           # Layout da conta
    profile/page.tsx
    orders/page.tsx
  @modal/
    default.tsx
    (.)products/[slug]/page.tsx  # Modal de visualização rápida do produto

App de Dashboard

app/
  (auth)/
    login/page.tsx
    register/page.tsx
  (dashboard)/
    layout.tsx
    page.tsx
    @sidebar/
      default.tsx
      page.tsx
    @main/
      default.tsx
      [section]/page.tsx
    settings/
      layout.tsx
      page.tsx
      profile/page.tsx
      billing/page.tsx

## Exemplo de Trabalho

### Exemplo 1: Usuário pergunta "Como crio um padrão de modal de fotos?"

**Prompt do usuário:** "Quero que clicar em uma miniatura de foto abra um modal, mas compartilhar o URL deve mostrar a página da foto completa."

**A resposta guiada pela habilidade produziria esta estrutura de arquivos:**

app/ layout.tsx @modal/ default.tsx (.)photo/[id]/page.tsx # Versão Modal photo/[id]/page.tsx # Versão Página Completa gallery/page.tsx # Grade de miniaturas

```tsx
// app/layout.tsx
export default function RootLayout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        {modal}
      </body>
    </html>
  );
}

// app/@modal/default.tsx
export default function Default() {
  return null; // Sem modal por padrão
}

// app/@modal/(.)photo/[id]/page.tsx
import { Modal } from "@/components/Modal";
 
export default async function PhotoModal({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const photo = await getPhoto(id);
 
  return (
    <Modal>
      <img src={photo.url} alt={photo.alt} />
      <p>{photo.description}</p>
    </Modal>
  );
}

// app/photo/[id]/page.tsx
export default async function PhotoPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const photo = await getPhoto(id);
 
  return (
    <main className="flex min-h-screen items-center justify-center">
      <img src={photo.url} alt={photo.alt} className="max-w-4xl" />
      <h1>{photo.title}</h1>
      <p>{photo.description}</p>
    </main>
  );
}

Exemplo 2: Usuário pergunta "Como devo organizar as rotas para um aplicativo SaaS?"

A resposta guiada pela habilidade recomendaria:

• Grupos de rotas: (marketing) para páginas públicas, (app) para o dashboard autenticado, (auth) para login/cadastro
• Rotas paralelas para a barra lateral do dashboard + conteúdo principal
• Middleware para redirecionamentos de autenticação
• Estrutura de arquivos específica com layouts por grupo

Mergulho Profundo

Como a Habilidade Funciona

Esta habilidade fornece ao Claude:

1. Referência completa de convenções de arquivos - Cada arquivo especial no App Router e o que ele faz
2. Árvores de decisão - Lógica estruturada para escolher o padrão certo para um requisito
3. Detecção de anti-padrões - Erros comuns sobre os quais a habilidade alerta proativamente
4. Modelos de estrutura de arquivos - Arquiteturas prontas para tipos de aplicativos comuns

Personalização

Estenda esta habilidade adicionando:

• Convenções de estrutura de rotas específicas do seu projeto
• Padrões de middleware personalizados (por exemplo, testes A/B, flags de recursos)
• Convenções de nomenclatura específicas da organização para grupos de rotas

Como Instalar

mkdir -p .claude/skills/nextjs-routing
# Cole o conteúdo da Receita em .claude/skills/nextjs-routing/SKILL.md

Armadilhas

• Slots de rotas paralelas são posicionais - Se você renomear uma pasta de slot, deverá atualizar as props do layout pai para corresponder.
• Rotas de interceptação usam caminhos relativos ao sistema de arquivos - (.) significa o mesmo nível no sistema de arquivos, não no nível da URL. Isso confunde muitos desenvolvedores.
• default.tsx é obrigatório para rotas paralelas - Sem ele, uma atualização manual em uma URL que não corresponde ao slot renderizará um 404 em vez do fallback.
• Grupos de rotas podem criar múltiplos layouts raiz - Se dois grupos de rotas na raiz do app tiverem cada um um layout.tsx, a navegação entre eles causa uma recarga completa da página.
• params é um Promise no Next.js 15+ - Você deve await params em componentes de página e layout.

Alternativas

FAQs

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  // ...
}

export default function RootLayout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}{modal}</body>
    </html>
  );
}

Relacionado

• App Router
• Layouts
• Rotas Paralelas
• Rotas de Interceptação
• Middleware
• Habilidade Next.js Data Fetching