Estrutura e organização do projeto
Esta página apresenta uma visão geral de todas as convenções de pastas e arquivos do Next.js, e recomendações para organizar seu projeto.
Convenções de pastas e arquivos
Pastas de nível superior
As pastas de nível superior são usadas para organizar o código e os ativos estáticos do seu app.

app | App Router |
pages | Pages Router |
public | Ativos estáticos a serem servidos |
src | Pasta opcional com o código-fonte do app |
Arquivos de nível superior
Os arquivos de nível superior são usados para configurar seu app, gerenciar dependências, executar o proxy, integrar ferramentas de monitoramento e definir variáveis de ambiente.
| Next.js | |
next.config.js | Arquivo de configuração do Next.js |
package.json | Dependências e scripts do projeto |
instrumentation.ts | Arquivo de OpenTelemetry e instrumentação |
proxy.ts | Proxy de requisições do Next.js |
.env | Variáveis de ambiente (não devem ser versionadas) |
.env.local | Variáveis de ambiente locais (não devem ser versionadas) |
.env.production | Variáveis de ambiente de produção (não devem ser versionadas) |
.env.development | Variáveis de ambiente de desenvolvimento (não devem ser versionadas) |
eslint.config.mjs | Arquivo de configuração do ESLint |
.gitignore | Arquivos e pastas do Git a serem ignorados |
next-env.d.ts | Arquivo de declaração TypeScript do Next.js (não deve ser versionado) |
tsconfig.json | Arquivo de configuração do TypeScript |
jsconfig.json | Arquivo de configuração do JavaScript |
Arquivos de roteamento
Adicione page para expor uma rota, layout para interface compartilhada como cabeçalho, navegação ou rodapé, loading para esqueletos, error para error boundaries e route para APIs.
layout | .js .jsx .tsx | Layout |
page | .js .jsx .tsx | Página |
loading | .js .jsx .tsx | Interface de carregamento |
not-found | .js .jsx .tsx | Interface de não encontrado |
error | .js .jsx .tsx | Interface de erro |
global-error | .js .jsx .tsx | Interface de erro global |
route | .js .ts | Endpoint de API |
template | .js .jsx .tsx | Layout renderizado de novo |
default | .js .jsx .tsx | Página de fallback de rota paralela |
Rotas aninhadas
Pastas definem segmentos de URL. Aninhar pastas aninha segmentos. Layouts em qualquer nível envolvem seus segmentos filhos. Uma rota se torna pública quando existe um arquivo page ou route.
| Caminho | Padrão de URL | Observações |
|---|---|---|
app/layout.tsx | — | Layout raiz envolve todas as rotas |
app/blog/layout.tsx | — | Envolve /blog e seus descendentes |
app/page.tsx | / | Rota pública |
app/blog/page.tsx | /blog | Rota pública |
app/blog/authors/page.tsx | /blog/authors | Rota pública |
Rotas dinâmicas
Parametrize segmentos com colchetes. Use [segment] para um único parâmetro, [...segment] para catch‑all e [[...segment]] para catch‑all opcional. Acesse os valores pela prop params.
| Caminho | Padrão de URL |
|---|---|
app/blog/[slug]/page.tsx | /blog/my-first-post |
app/shop/[...slug]/page.tsx | /shop/clothing, /shop/clothing/shirts |
app/docs/[[...slug]]/page.tsx | /docs, /docs/layouts-and-pages, /docs/api-reference/use-router |
Grupos de rotas e pastas privadas
Organize o código sem alterar as URLs com grupos de rotas (group), e posicione arquivos não roteáveis junto ao código com pastas privadas _folder.
| Caminho | Padrão de URL | Observações |
|---|---|---|
app/(marketing)/page.tsx | / | Grupo omitido da URL |
app/(shop)/cart/page.tsx | /cart | Compartilha layouts dentro de (shop) |
app/blog/_components/Post.tsx | — | Não roteável; lugar seguro para utilitários de interface |
app/blog/_lib/data.ts | — | Não roteável; lugar seguro para utilitários |
Rotas paralelas e interceptadas
Esses recursos se encaixam em padrões de interface específicos, como layouts baseados em slots ou roteamento de modais.
Use @slot para slots nomeados renderizados por um layout pai. Use padrões de interceptação para renderizar outra rota dentro do layout atual sem alterar a URL, por exemplo, para mostrar uma visualização de detalhes como modal sobre uma lista.
| Padrão (docs) | Significado | Caso de uso comum |
|---|---|---|
@folder | Slot nomeado | Barra lateral + conteúdo principal |
(.)folder | Intercepta o mesmo nível | Pré-visualiza uma rota irmã em um modal |
(..)folder | Intercepta o pai | Abre um filho do pai como sobreposição |
(..)(..)folder | Intercepta dois níveis | Sobreposição em um nível muito aninhado |
(...)folder | Intercepta a partir da raiz | Mostra uma rota qualquer na visualização atual |
Convenções de arquivos de metadados
Ícones do app
favicon | .ico | Arquivo de favicon |
icon | .ico .jpg .jpeg .png .svg | Arquivo de ícone do app |
icon | .js .ts .tsx | Ícone do app gerado |
apple-icon | .jpg .jpeg .png | Arquivo de ícone do app para Apple |
apple-icon | .js .ts .tsx | Ícone do app para Apple gerado |
Open Graph e imagens do Twitter
opengraph-image | .jpg .jpeg .png .gif | Arquivo de imagem Open Graph |
opengraph-image | .js .ts .tsx | Imagem Open Graph gerada |
twitter-image | .jpg .jpeg .png .gif | Arquivo de imagem do Twitter |
twitter-image | .js .ts .tsx | Imagem do Twitter gerada |
SEO
sitemap | .xml | Arquivo de sitemap |
sitemap | .js .ts | Sitemap gerado |
robots | .txt | Arquivo robots |
robots | .js .ts | Arquivo robots gerado |
Organizando seu projeto
O Next.js não impõe uma forma específica de organizar e posicionar os arquivos do projeto. Mas ele oferece alguns recursos para ajudar você a organizá-lo.
Hierarquia de componentes
Os componentes definidos em arquivos especiais são renderizados em uma hierarquia específica:
layout.jstemplate.jserror.js(error boundary do React)loading.js(Suspense boundary do React)not-found.js(error boundary do React para a interface de "não encontrado")page.jsoulayout.jsaninhado


Os componentes são renderizados recursivamente em rotas aninhadas, ou seja, os componentes de um segmento de rota ficam aninhados dentro dos componentes do segmento pai.


Colocalização
No diretório app, pastas aninhadas definem a estrutura de rotas. Cada pasta representa um segmento de rota mapeado para um segmento correspondente em um caminho de URL.
No entanto, mesmo que a estrutura de rotas seja definida por pastas, uma rota não fica acessível publicamente até que um arquivo page.js ou route.js seja adicionado ao segmento de rota.


E, mesmo quando uma rota se torna acessível publicamente, apenas o conteúdo retornado por page.js ou route.js é enviado ao cliente.


Isso significa que os arquivos do projeto podem ser colocalizados com segurança dentro de segmentos de rota no diretório app sem se tornarem roteáveis por acidente.


Bom saber: embora você possa colocalizar os arquivos do projeto em
app, não é obrigatório. Se preferir, pode mantê-los fora do diretórioapp.
Pastas privadas
Pastas privadas podem ser criadas prefixando uma pasta com um sublinhado: _folderName
Isso indica que a pasta é um detalhe de implementação privado e não deve ser considerada pelo sistema de roteamento, excluindo assim a pasta e todas as suas subpastas do roteamento.


Como os arquivos no diretório app podem ser colocalizados com segurança por padrão, pastas privadas não são necessárias para a colocalização. No entanto, elas podem ser úteis para:
- Separar a lógica de interface da lógica de roteamento.
- Organizar de forma consistente os arquivos internos em todo o projeto e no ecossistema do Next.js.
- Ordenar e agrupar arquivos em editores de código.
- Evitar possíveis conflitos de nome com futuras convenções de arquivos do Next.js.
Bom saber:
- Embora não seja uma convenção do framework, você também pode considerar marcar como "privados" os arquivos fora de pastas privadas, usando o mesmo padrão de sublinhado.
- Você pode criar segmentos de URL que começam com sublinhado prefixando o nome da pasta com
%5F(a forma codificada em URL de um sublinhado):%5FfolderName.- Se você não usar pastas privadas, vale conhecer as convenções de arquivos especiais do Next.js para evitar conflitos de nome inesperados.
Grupos de rotas
Grupos de rotas podem ser criados envolvendo uma pasta em parênteses: (folderName)
Isso indica que a pasta serve para organização e não deve ser incluída no caminho da URL da rota.


Grupos de rotas são úteis para:
- Organizar rotas por seção do site, intenção ou equipe. Por exemplo: páginas de marketing, páginas de administração etc.
- Habilitar layouts aninhados no mesmo nível de segmento de rota:
Pasta src
O Next.js permite armazenar o código do app (incluindo app) dentro de uma pasta src opcional. Isso separa o código do app dos arquivos de configuração do projeto, que geralmente ficam na raiz.


Exemplos
A seção a seguir lista uma visão geral de alto nível das estratégias comuns. A conclusão mais simples é escolher uma estratégia que funcione para você e sua equipe e mantê-la consistente em todo o projeto.
Bom saber: nos exemplos abaixo, usamos as pastas
componentselibcomo marcadores genéricos. Os nomes não têm significado especial para o framework, e seus projetos podem usar outras pastas, comoui,utils,hooks,stylesetc.
Armazenar arquivos do projeto fora de app
Essa estratégia armazena todo o código do app em pastas compartilhadas na raiz do projeto e mantém o diretório app exclusivamente para roteamento.


Armazenar arquivos do projeto em pastas de nível superior dentro de app
Essa estratégia armazena todo o código do app em pastas compartilhadas na raiz do diretório app.


Dividir arquivos do projeto por funcionalidade ou rota
Essa estratégia armazena o código do app compartilhado globalmente na raiz do diretório app e divide o código mais específico nos segmentos de rota que o utilizam.


Organizar rotas sem afetar o caminho da URL
Para organizar rotas sem afetar a URL, crie um grupo para manter as rotas relacionadas juntas. As pastas entre parênteses são omitidas da URL (por exemplo, (marketing) ou (shop)).


Mesmo que as rotas dentro de (marketing) e (shop) compartilhem a mesma hierarquia de URL, você pode criar um layout diferente para cada grupo adicionando um arquivo layout.js dentro das pastas. Esses layouts são aninhados dentro do layout existente do app.


Escolher segmentos específicos para um layout
Para incluir rotas específicas em um layout, crie um novo grupo de rotas (por exemplo, (shop)) e mova para dentro dele as rotas que compartilham o mesmo layout (por exemplo, account e cart). As rotas fora do grupo não compartilharão o layout (por exemplo, checkout).


Escolher esqueletos de carregamento para uma rota específica
Para aplicar um esqueleto de carregamento por meio de um arquivo loading.js a uma rota específica, crie um novo grupo de rotas (por exemplo, /(overview)) e depois mova seu loading.tsx para dentro desse grupo.


Agora, o arquivo loading.tsx se aplica apenas à página de visão geral do dashboard, em vez de todas as páginas do dashboard, sem afetar a estrutura do caminho da URL.
Criar múltiplos layouts raiz
Para criar múltiplos layouts raiz, remova o arquivo layout.js de nível superior e adicione um arquivo layout.js dentro de cada grupo de rotas. Isso é útil para dividir um app em seções com interface ou experiência completamente diferentes. Você precisa adicionar as tags <html> e <body> a cada layout raiz.


No exemplo acima, (marketing) e (shop) têm, cada um, seu próprio layout raiz.