Next.js: Roteamento por Sistema de Arquivos do App Router

src/app/
├── page.tsx                    # → /
├── about/
│   └── page.tsx                # → /about
├── products/
│   ├── page.tsx                # → /products
│   └── [id]/
│       ├── page.tsx            # → /products/1, /products/2
│       └── reviews/
│           └── page.tsx        # → /products/1/reviews
└── api/
    └── products/
        └── route.ts            # → /api/products (GET/POST)

Diagrama: page.tsx; /; about/page.tsx; /about; products/page.tsx; /products.

// ============================================
// Criar Página /about
// Documento:src/app/about/page.tsx
// Basta criar um arquivo, Registro Automático de Rota
// ============================================

export default function AboutPage() {
  return (
    <div className="max-w-2xl mx-auto p-8">
      <h1 className="text-3xl font-bold">Sobre o TaskFlow</h1>
      <p className="mt-4 text-gray-600 leading-relaxed">
        TaskFlow é uma plataforma colaborativa de gerenciamento de projetos que ajuda
        equipes a planejar, acompanhar e entregar projetos com eficiência. Construído com
        Next.js 16 e React 19, oferece atualizações em tempo real, colaboração
        perfeita e segurança de nível empresarial.
      </p>
      <div className="mt-8 grid grid-cols-3 gap-4">
        <div className="p-4 bg-blue-50 rounded-lg text-center">
          <div className="text-2xl font-bold text-blue-600">10K+</div>
          <div className="text-sm text-gray-500">Usuários Ativos</div>
        </div>
        <div className="p-4 bg-green-50 rounded-lg text-center">
          <div className="text-2xl font-bold text-green-600">50K+</div>
          <div className="text-sm text-gray-500">Projetos</div>
        </div>
        <div className="p-4 bg-purple-50 rounded-lg text-center">
          <div className="text-2xl font-bold text-purple-600">99.9%</div>
          <div className="text-sm text-gray-500">Tempo de Atividade</div>
        </div>
      </div>
    </div>
  );
}

Conteúdo: Sobre o TaskFlow | TaskFlow é uma plataforma colaborativa | 10K+ | Usuários Ativos

Visite http://localhost:3000/about Veja:
Sobre o TaskFlow
TaskFlow é uma plataforma colaborativa de gerenciamento de projetos...
10K+  Usuários Ativos | 50K+  Projetos | 99.9%  Tempo de Atividade

Diagrama: app/products; page.tsx → /products; [id; page.tsx → /products/1; /products/2.

// ============================================
// Página de Detalhes do Produto — Roteamento Dinâmico [id]
// Documento:src/app/products/[id]/page.tsx
// ============================================

// No Next.js 16, params é uma Promise (assíncrono)
export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await fetch(`https://fakestoreapi.com/products/${id}`);

  return (
    <div className="container mx-auto p-8">
      <div className="flex gap-8">
        <img
          src={product.image}
          alt={product.title}
          className="w-80 h-80 object-contain"
        />
        <div>
          <h1 className="text-2xl font-bold">{product.title}</h1>
          <p className="text-xl text-green-600 font-bold mt-2">
            ${product.price}
          </p>
          <p className="text-sm text-gray-500 mt-1">
            Categoria: {product.category}
          </p>
          <p className="mt-4 text-gray-700">{product.description}</p>
        </div>
      </div>
    </div>
  );
}

O componente do servidor busca e renderiza dados.

Visite /products/1 Veja:
Fjallraven - Foldsack No. 1 Backpack
$109.95
Categoria: men's clothing
Sua mochila perfeita para viagens de um dia e caminhadas...

Diagrama: app/docs; [...slug; page.tsx; /docs/getting-started; /docs/guides/installation; /docs/api/authentication/overview.

// ============================================
// Catch-all — Páginas de Documentos Multi-Nível
// Documento:src/app/docs/[...slug]/page.tsx
// ============================================

export default async function DocsPage({
  params,
}: {
  params: Promise<{ slug: string[] }>;
}) {
  const { slug } = await params;

  return (
    <div className="container mx-auto p-8">
      <nav className="text-sm text-gray-500 mb-4">
        Início / Docs / {slug.join(" / ")}
      </nav>
      <h1 className="text-3xl font-bold">Docs: {slug.join(" > ")}</h1>
      <div className="mt-8 p-6 bg-yellow-50 border border-yellow-200 rounded-lg">
        <p className="font-medium">Você está visualizando documentação para:</p>
        <ul className="mt-2 list-disc list-inside">
          {slug.map((segment, index) => (
            <li key={index}>
              Nível {index + 1}: <code className="bg-gray-100 px-2 py-0.5 rounded">{segment}</code>
            </li>
          ))}
        </ul>
      </div>
      <p className="mt-4 text-gray-600">
        Profundidade total: {slug.length} níveis
      </p>
    </div>
  );
}

DocsPage renderiza sua UI.

Visite /docs/getting-started/installation Veja:
Início / Docs / getting-started / installation
Docs: getting-started > installation

Você está visualizando documentação para:
  - Nível 1: getting-started
  - Nível 2: installation
Profundidade total: 2 níveis

Diagrama: app/categories; [[...catchAll; page.tsx; /categories; /categories/electronics; /categories/electronics/phones.

// ============================================
// Catch-all Opcional — Página de Navegação de Categoria
// Documento:src/app/categories/[[...categories]]/page.tsx
// Tanto /categories quanto /categories/electronics entram em vigor
// ============================================

export default async function CategoriesPage({
  params,
}: {
  params: Promise<{ categories?: string[] }>;
}) {
  const { categories } = await params;

  const allProducts = await fetch("https://fakestoreapi.com/products");
  const categoriesList = [...new Set(allProducts.map(p => p.category))];

  const filteredProducts = categories
    ? allProducts.filter(p => p.category === categories[0])
    : allProducts;

  return (
    <div className="container mx-auto p-8">
      <h1 className="text-3xl font-bold mb-6">
        {categories ? `Categoria: ${categories[0]}` : "Todas as Categorias"}
      </h1>

      {!categories && (
        <div className="flex gap-2 mb-8 flex-wrap">
          {categoriesList.map(cat => (
            <a
              key={cat}
              href={`/categories/${encodeURIComponent(cat)}`}
              className="px-4 py-2 bg-gray-100 rounded-full hover:bg-blue-100"
            >
              {cat}
            </a>
          ))}
        </div>
      )}

      <div className="grid grid-cols-4 gap-6">
        {filteredProducts.slice(0, 8).map(p => (
          <div key={p.id} className="border rounded-lg p-4 hover:shadow-lg">
            <img src={p.image} alt={p.title} className="h-40 mx-auto" />
            <p className="mt-2 font-medium text-sm truncate">{p.title}</p>
            <p className="text-green-600 font-bold">${p.price}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

A busca de dados do lado do servidor renderiza a lista de itens.

Visite /categories Veja:
Botões de Todas as Categorias(electronics, jewelery, men's clothing, women's clothing)

Visite /categories/electronics Veja:
Categoria: electronics
Mostrar apenas produtos eletrônicos(8 Cards de Produto)

Diagrama: Navegação do Usuário; loading.tsx Exibição de Wireframe; page.tsx Dados Prontos; Página Completa.

// ============================================
// Carregando a tela de esqueleto — Exibida quando os dados da página estão sendo recuperados
// Documento:src/app/products/loading.tsx
// ============================================

export default function ProductsLoading() {
  return (
    <div className="container mx-auto p-8">
      <div className="h-8 w-48 bg-gray-200 rounded animate-pulse mb-6" />
      <div className="grid grid-cols-4 gap-6">
        {Array.from({ length: 8 }).map((_, i) => (
          <div key={i} className="border rounded-lg p-4">
            <div className="h-40 bg-gray-200 rounded animate-pulse" />
            <div className="h-4 bg-gray-200 rounded mt-2 animate-pulse" />
            <div className="h-4 w-16 bg-gray-200 rounded mt-2 animate-pulse" />
          </div>
        ))}
      </div>
    </div>
  );
}

Renderiza uma lista de itens usando .map().

Ao visitar /products, exibe até que o carregamento de dados esteja completo:
8 Cartões de placeholder cinza(Animação com Pulsos)
Após o carregamento dos dados ser concluído, O conteúdo de placeholder é automaticamente substituído pelo conteúdo real
Sem cintilação, Sem tela branca, Transição Suave

A página renderiza como descrito acima, com a UI atualizando baseada no comportamento descrito.

// ============================================
// Limite de Erro — Capturando Erros de Componentes Filhos
// Documento:src/app/products/error.tsx
// ============================================

'use client';

export default function ProductsError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div className="container mx-auto p-8 text-center">
      <div className="max-w-md mx-auto">
        <h2 className="text-2xl font-bold text-red-600 mb-4">
          Algo deu errado!
        </h2>
        <p className="text-gray-600 mb-6">
          {error.message || "Falha ao carregar produtos. Por favor, tente novamente."}
        </p>
        <button
          onClick={reset}
          className="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
        >
          Tentar Novamente
        </button>
      </div>
    </div>
  );
}

Conteúdo: Algo deu errado! | Tentar Novamente

Quando a recuperação de dados da página do produto falha, Mostra:
Algo deu errado!
Falha ao carregar produtos. Por favor, tente novamente.
[Try Again] botão → Clique para tentar novamente automaticamente

---
## 6. Route Handlers (Rotas de API)

### (1) Uso Básico de route.ts

```mermaid
graph LR
    A[Requisição do Cliente] --> B[route.ts]
    B --> C[GET /api/products]
    B --> D[POST /api/products]
    B --> E[PUT /api/products/:id]
    B --> F[DELETE /api/products/:id]

    style B fill:#cce5ff

---
## 7. Exemplo Completo: Sistema de Navegação de Produtos E-commerce

```tsx
// ============================================
// Exemplo Abrangente: Sistema de Navegação de Produtos E-commerce
// Páginas Cobertas, Layout, Loading, Error, Roteamento de API
// ============================================

// src/app/layout.tsx — Layout Raiz
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="pt-BR">
      <body className="bg-gray-50">
        <nav className="bg-white shadow-sm p-4">
          <a href="/" className="text-xl font-bold text-blue-600">
            ShopHub
          </a>
        </nav>
        <main>{children}</main>
      </body>
    </html>
  );
}

// src/app/page.tsx — Início
export default function HomePage() {
  return (
    <div className="container mx-auto p-8 text-center">
      <h1 className="text-4xl font-bold">Bem-vindo ao ShopHub</h1>
      <p className="mt-4 text-gray-600">
        Navegue pela nossa coleção de produtos incríveis.
      </p>
      <a
        href="/products"
        className="inline-block mt-6 px-8 py-3 bg-blue-600 text-white rounded-lg"
      >
        Navegar Produtos
      </a>
    </div>
  );
}

// src/app/products/page.tsx — Lista de Produtos
export default async function ProductsPage() {
  const products = await fetch(
    "https://fakestoreapi.com/products"
  );

  return (
    <div className="container mx-auto p-8">
      <h1 className="text-3xl font-bold mb-6">Todos os Produtos</h1>
      <div className="grid grid-cols-4 gap-6">
        {products.map(p => (
          <a
            key={p.id}
            href={`/products/${p.id}`}
            className="border rounded-lg p-4 bg-white hover:shadow-lg"
          >
            <img
              src={p.image}
              alt={p.title}
              className="h-40 mx-auto"
            />
            <p className="mt-2 font-medium text-sm">{p.title}</p>
            <p className="text-green-600 font-bold mt-1">${p.price}</p>
          </a>
        ))}
      </div>
    </div>
  );
}

// src/app/products/[id]/page.tsx — Detalhes do Produto
export default async function ProductDetailPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await fetch(
    `https://fakestoreapi.com/products/${id}`
  );

  if (!product) {
    notFound();
  }

  return (
    <div className="container mx-auto p-8">
      <a
        href="/products"
        className="text-blue-600 hover:underline mb-4 inline-block"
      >
        &larr; Voltar para produtos
      </a>
      <div className="flex gap-8 bg-white p-8 rounded-lg shadow">
        <img
          src={product.image}
          alt={product.title}
          className="w-96 h-96 object-contain"
        />
        <div>
          <h1 className="text-3xl font-bold">{product.title}</h1>
          <p className="text-2xl text-green-600 font-bold mt-4">
            ${product.price}
          </p>
          <p className="mt-6 text-gray-700 leading-relaxed">
            {product.description}
          </p>
          <button className="mt-6 px-8 py-3 bg-blue-600 text-white rounded-lg">
            Adicionar ao Carrinho
          </button>
        </div>
      </div>
    </div>
  );
}

// src/app/products/loading.tsx — Carregando a tela de esqueleto
export default function ProductsLoading() {
  return (
    <div className="container mx-auto p-8">
      <div className="h-8 w-48 bg-gray-200 rounded animate-pulse mb-6" />
      <div className="grid grid-cols-4 gap-6">
        {Array.from({ length: 8 }).map((_, i) => (
          <div key={i} className="border rounded-lg p-4 bg-white">
            <div className="h-40 bg-gray-200 rounded animate-pulse" />
            <div className="h-4 bg-gray-200 rounded mt-2 animate-pulse" />
            <div className="h-4 w-16 bg-gray-200 rounded mt-2 animate-pulse" />
          </div>
        ))}
      </div>
    </div>
  );
}

// src/app/products/error.tsx — Limite de Erro
'use client';
export default function ProductsError({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div className="container mx-auto p-8 text-center">
      <h2 className="text-2xl font-bold text-red-600">
        Falha ao carregar produtos
      </h2>
      <button
        onClick={reset}
        className="mt-4 px-6 py-2 bg-blue-600 text-white rounded-lg"
      >
        Tentar Novamente
      </button>
    </div>
  );
}

Início(/):
  Bem-vindo ao ShopHub → [Navegar Produtos]

Lista de Produtos(/products):
  Carregando... → 8 Telas de esqueleto cinzas
  Carregamento completo → Grade de Cards de Produto(Inclui imagens, Título, Preço)

Detalhes do Produto(/products/1):
  Imagens do Produto (esquerda) + Título/Preço/Descrição/Adicionar ao Carrinho (direita)
  ← Voltar para produtos Link Voltar para Lista

Status de Erro:
  Falha ao carregar produtos
  [Tentar Novamente] botão

Status 404:
  Automaticamente do raiz not-found.tsx Processamento