📚 Módulo 00: Introdução, Arquitetura Multirepo e SSR (Next.js)

Seja bem-vindo à TecLoja 04, a versão definitiva do nosso e-commerce. Diferente do projeto anterior (TecLoja 03) onde o frontend era uma Single Page Application estática, aqui adotaremos o Next.js.

Neste módulo, estudaremos como o Server-Side Rendering altera profundamente nossa infraestrutura de servidores e segurança.

🏛️ 1. A Evolução: Por que sair do Vite (SPA) para o Next.js (SSR)?

🐢 O Problema do React SPA Clássico (Vite)

Quando um cliente (ou robô do Google) acessa uma SPA, o servidor devolve um HTML em branco e um arquivo JavaScript pesado. O navegador precisa baixar o JS, processar a tela em branco, e só então disparar requisições para a API e renderizar a vitrine de produtos.

🚀 A Solução: Next.js (Server Components e SSR)

O Next.js roda em um Servidor Node.js próprio. Quando o cliente requisita o site, o servidor do Next.js pré-renderiza a página HTML completa com todos os produtos, cores e textos já injetados, e devolve a página pronta.

🗺️ 2. Diagrama de Comunicação e Infraestrutura Cloud

No novo fluxo, teremos a introdução de um servidor intermediário (BFF - Backend For Frontend):

flowchart TD
    %% Styling
    classDef client fill:#61dafb,stroke:#20232a,stroke-width:2px,color:#000;
    classDef next fill:#000000,stroke:#333,stroke-width:2px,color:#fff;
    classDef api fill:#ea2845,stroke:#3b0713,stroke-width:2px,color:#fff;
    classDef db fill:#003545,stroke:#001f29,stroke-width:2px,color:#fff;

    Navegador["💻 Navegador do Usuário"]:::client
    Vercel["▲ Servidor Next.js <br> (Node.js SSR / BFF)"]:::next
    Render["🐳 Render Containers <br> (API NestJS Core)"]:::api
    Neon["🛢️ Neon PostgreSQL <br> (Database Serverless)"]:::db

    Navegador -->|1. Acessa tecloja.com| Vercel
    Vercel -->|2. Busca Produtos (Server Fetch)| Render
    Render -->|3. ORM Prisma| Neon
    Vercel -->|4. Retorna HTML renderizado| Navegador
    
    Navegador -.->|5. Ações dinâmicas (Client-side)| Vercel

🛡️ O Fim do CORS e a Segurança BFF

Na TecLoja 03, o React rodava no navegador e sofria com bloqueios de CORS ao falar com o NestJS. Pior, salvávamos o JWT no localStorage, sujeito a ataques de roubo (XSS).

No Next.js, o navegador do usuário conversa APENAS com as Rotas Internas do Next.js (BFF). É o servidor Node do Next.js que faz as chamadas para a API NestJS. O token JWT fica armazenado com extrema segurança em um Cookie HttpOnly e Secure, onde hackers não conseguem acessar via JavaScript!

📂 3. Estrutura de Pastas dos Repositórios

A estrutura do Backend (NestJS) se manterá fiel à arquitetura corporativa sólida que já aprendemos. O Frontend (Next.js), entretanto, adota o moderno App Router.

⚛️ Repositório 2: tecloja-frontend-next (Next.js)

tecloja-frontend-next/
├── src/
│   ├── app/                    # O coração do App Router (Roteamento baseado em pastas)
│   │   ├── layout.tsx          # Layout global e Header (Navbar)
│   │   ├── page.tsx            # Rota / (Catálogo Renderizado no Servidor)
│   │   ├── carrinho/
│   │   │   └── page.tsx        # Rota /carrinho (Client Component)
│   │   ├── admin/
│   │   │   ├── layout.tsx      # Layout e Proteção de rota administrativa
│   │   │   ├── page.tsx        # Tabela de CRUD de produtos
│   │   │   └── novo/page.tsx   # Formulário
│   │   └── api/                # Route Handlers (O BFF)
│   │       └── auth/route.ts   # Rota que gerencia o Cookie de login
│   ├── components/             # Componentes de UI (Botões, Cards)
│   ├── store/                  # Estado global (Zustand)
│   │   └── useCartStore.ts     # Gerenciamento reativo do carrinho
│   ├── lib/
│   │   └── actions.ts          # Server Actions para mutações de dados
│   ├── types/                  # Interfaces TypeScript correspondentes aos DTOs
│   └── styles/
│       └── globals.css         # Reset e importação do TailwindCSS
├── tailwind.config.ts          # Arquivo de configuração do utilitário CSS
├── next.config.mjs             # Configuração do motor Next.js
└── Dockerfile                  # Empacotamento Node standalone

✅ Pré-Requisitos deste Módulo

Para iniciar o desenvolvimento da TecLoja 04 com Next.js e SSR, certifique-se de possuir:

🤔 Por que fizemos assim?

🔍 Checkpoint

  1. Node LTS Ativo: Rode node -v em seu console e verifique se a versão local atende ao requisito mínimo (versões 18 ou superior).
  2. Hierarquia Estruturada: Crie a pasta do projeto tecloja-frontend-next separadamente e examine o modelo de pastas físicas, diferenciando a pasta /app com os arquivos layout.tsx e page.tsx.

⚠️ Erros Comuns

Erro Causa Solução
Erro React hooks cannot be used in Server Components ao iniciar o Next.js O desenvolvedor tentou utilizar hooks de estado (useState, useEffect) ou hooks de roteamento em um componente que roda no servidor. Por padrão, os componentes do App Router rodam no servidor. Para transformá-los em componentes interativos do cliente, declare a diretiva "use client" como a primeiríssima linha do arquivo.
O JavaScript do frontend não consegue ler o token JWT no document.cookie A propriedade HttpOnly está ativa por design no cookie gravado pelo BFF. Não tente acessar o token direto via JavaScript no navegador do cliente. Toda chamada protegida que requeira autenticação Bearer JWT deve passar pelo BFF no servidor do Next.js.
Lentidão inexplicável no carregamento inicial de Server Components O componente realiza requisições sequenciais síncronas bloqueantes (cachoeira de fetches) ou consulta dados que deveriam estar cacheados. Utilize carregamentos assíncronos concorrentes via Promise.all() ou implemente as diretivas de revalidação incremental de estáticos (ISR) do Next.js.

🏁 Conclusão

Compreendemos por que E-commerces de ponta abandonaram as SPAs tradicionais em favor de frameworks full-stack de Server-Side Rendering. No Módulo 01, revisitaremos rapidamente a fundação de dados, criando nossas tabelas com o Prisma ORM e PostgreSQL!

Voltar para o Sumário