Estrutura do Projeto

Um dos primeiros choques ao chegar no Next.js é a ausência de app.module.ts e do arquivo de rotas. A estrutura de pastas é a configuração de rotas.

Estrutura Angular vs. Next.js

Compare as duas estruturas lado a lado:

Angular

src/
  app/
    app.module.ts           # módulo raiz
    app.component.ts        # componente raiz
    app-routing.module.ts   # configuração de rotas
    core/
      auth.service.ts       # serviços singleton
      http.interceptor.ts
    shared/
      components/           # componentes reutilizáveis
        button/
          button.component.ts
          button.component.html
          button.component.scss
      pipes/
      directives/
    features/
      dashboard/
        dashboard.module.ts
        dashboard.component.ts
        dashboard.service.ts
        dashboard-routing.module.ts
      users/
        users.module.ts
        users.component.ts
angular.json
tsconfig.json

Next.js (App Router)

app/
  layout.tsx              # layout raiz (obrigatório, html+body)
  page.tsx                # página → rota "/"
  loading.tsx             # skeleton automático (Suspense)
  error.tsx               # boundary de erro
  not-found.tsx           # 404 customizado
  _components/            # componentes privados (não são rotas)
    Button.tsx
    Sidebar.tsx
  (marketing)/            # route group — sem efeito na URL
    about/
      page.tsx            # → rota "/about"
    layout.tsx
  dashboard/
    layout.tsx            # layout compartilhado de /dashboard
    page.tsx              # → rota "/dashboard"
    loading.tsx
    settings/
      page.tsx            # → rota "/dashboard/settings"
  api/
    users/
      route.ts            # endpoint GET/POST /api/users
  lib/
    db.ts                 # utilitários de servidor
    auth.ts
public/
  logo.svg
next.config.ts
tsconfig.json

Arquivos especiais do App Router

O Next.js reserva nomes de arquivo especiais dentro da pasta app/. Cada um tem um papel específico no ciclo de vida da rota:

app/
  layout.tsx      ← compartilhado entre TODAS as rotas filhas
  page.tsx        ← torna a rota pública ("/")
  loading.tsx     ← exibido enquanto page.tsx carrega
  error.tsx       ← captura erros em runtime (Error Boundary)
  not-found.tsx   ← chamado por notFound() ou URL inválida

  blog/
    layout.tsx    ← compartilhado entre /blog e /blog/[slug]
    page.tsx      ← rota "/blog"
    [slug]/
      page.tsx    ← rota "/blog/meu-post"

Arquivo	Função	Equivalente Angular
layout.tsx	UI compartilhada entre rotas filhas. Preserva estado na navegação.	app.component.html (parcial)
page.tsx	Conteúdo da rota. Torna a pasta uma rota pública.	@Component de rota
loading.tsx	Skeleton exibido automaticamente enquanto page.tsx carrega.	ngIf + flag isLoading
error.tsx	Error Boundary — captura erros em runtime da rota.	ErrorHandler global
not-found.tsx	Página 404 customizada para a rota.	Rota ** com redirect
route.ts	API endpoint (GET, POST, etc). Não renderiza UI.	Não há (Angular é frontend)

Route Groups e Pastas Privadas

Duas convenções de nomenclatura ajudam a organizar o projeto sem impactar as URLs:

(grupo)

Pasta entre parênteses é um Route Group — agrupa rotas para compartilhar layouts ou organizar o código, sem aparecer na URL.

_pasta

Pasta com underscore é uma pasta privada — nunca se torna uma rota. Use para componentes, hooks e utilitários colocalizados.

Exemplo com Route Groups

app/
  (marketing)/          # não aparece na URL
    page.tsx            # → "/"
    about/
      page.tsx          # → "/about"
    layout.tsx          # layout só para marketing
  (app)/
    dashboard/
      page.tsx          # → "/dashboard"
    profile/
      page.tsx          # → "/profile"
    layout.tsx          # layout com sidebar para o app

Tabela de equivalências

Angular	Next.js	Propósito
app.module.ts	app/layout.tsx	Ponto de entrada / wrapper raiz
app-routing.module.ts	Estrutura de pastas em app/	Definição de rotas
core/	app/lib/ ou lib/	Utilitários singleton, db, auth
shared/components/	app/_components/ ou components/	Componentes reutilizáveis
shared/pipes/	Funções TypeScript puras	Transformação de dados
features/xxx/xxx.service.ts	app/lib/xxx.ts (Server) ou Context (Client)	Lógica de negócio
assets/	public/	Arquivos estáticos
environments/	.env.local / .env.production	Variáveis de ambiente
styles.scss	app/globals.css	Estilos globais
angular.json	next.config.ts	Configuração do framework/build

ℹ

Dica: Diferente do Angular, no Next.js não existe um arquivo central de configuração de rotas. Se uma pasta dentro de app/ contém um page.tsx, ela se torna uma rota. Se não contém, é apenas organização de código.

Referência oficial: Project Structure — Next.js Docs ↗

← AnteriorPor que Next.js?

Próximo →Componentes