Estrutura projeto React: guia profissional de organização

Organizar um projeto React do zero parece simples até você ter 50 componentes na mesma pasta. A diferença entre um projeto que dá pra manter e um que vira um pesadelo está na estrutura de pastas. Neste guia, mostro como estruturar um projeto React profissional, com separação por funcionalidade e responsabilidades claras.

Passo 1: Defina a estrutura de pastas por funcionalidade

Em vez de agrupar arquivos por tipo (components/, hooks/, utils/), agrupe por funcionalidade. Crie uma pasta features/ ou modules/ com subpastas para cada módulo do sistema, como auth/, dashboard/, checkout/. Dentro de cada uma, coloque componentes, hooks e testes específicos daquela funcionalidade.

Erro comum: colocar tudo em src/components/ com subpastas genéricas. Isso força você a navegar por dezenas de pastas para encontrar um arquivo. A organização por funcionalidade encurta o caminho.

Passo 2: Separe responsabilidades em camadas

Mantenha uma pasta shared/ para código reutilizável entre funcionalidades: componentes de UI (botões, inputs), hooks globais, contextos e serviços de API. Dentro de shared/, use subpastas por tipo: ui/, hooks/, contexts/, services/.

Dica prática: um componente de botão fica em shared/ui/Button/. Um hook de autenticação fica em features/auth/hooks/useAuth.js. Testes ficam na mesma pasta do arquivo que testam.

Passo 3: Padronize exportações com index.js

Cada pasta de componente ou funcionalidade deve ter um index.js que exporta o que é público. Isso permite importar de forma limpa: import { Button } from '@/shared/ui' em vez de import Button from '@/shared/ui/Button/Button'.

Erro comum: esquecer o index.js e ter imports com caminhos longos e quebradiços. Quando você move um arquivo, precisa atualizar todos os imports.

Passo 4: Use aliases de importação

Configure aliases no jsconfig.json ou tsconfig.json para evitar caminhos relativos como ../../../components/. Use @/ para apontar para src/. Isso torna os imports mais legíveis e facilita a refatoração.

Dica prática: no Vite, configure resolve.alias no vite.config.js. No CRA, use o jsconfig.json com baseUrl: "src".

Passo 5: Mantenha estilos e assets organizados

Coloque estilos globais em src/styles/ e estilos específicos de componente dentro da pasta do componente (CSS Modules ou styled-components). Assets como imagens e fontes vão em src/assets/, com subpastas por tipo.

Erro comum: misturar estilos globais com locais ou colocar assets soltos na raiz de src/. Isso polui a navegação e dificulta encontrar o que você precisa.

Checklist rápido do que foi feito

• [ ] Pastas organizadas por funcionalidade (features/) com código específico
• [ ] Código compartilhado separado em shared/ com subpastas por tipo
• [ ] Cada pasta tem index.js exportando o conteúdo público
• [ ] Aliases configurados para imports limpos
• [ ] Estilos e assets em pastas dedicadas

FAQ

Qual a diferença entre organizar por tipo e por funcionalidade?

Organizar por tipo agrupa todos os componentes em uma pasta, todos os hooks em outra, etc. Por funcionalidade, cada módulo do sistema tem sua própria pasta com tudo que precisa. A segunda escala melhor em projetos grandes.

Devo usar uma única pasta 'components'?

Só se o projeto for muito pequeno (menos de 10 componentes). Em projetos maiores, a pasta 'components' vira um depósito. Prefira separar por funcionalidade e ter uma pasta 'shared/ui' para componentes reutilizáveis.

Como lidar com Context API na estrutura?

Coloque contextos em shared/contexts/ se forem globais (tema, autenticação) ou dentro da funcionalidade específica em features/. Evite um único arquivo de contexto que mistura tudo.

Preciso usar TypeScript para estruturar profissionalmente?

TypeScript ajuda, mas não substitui uma boa estrutura de pastas. Você pode ter um projeto JavaScript organizado e um TypeScript bagunçado. A estrutura vem antes do tipo.

O que fazer com testes na estrutura?

Coloque os testes na mesma pasta do arquivo que testam, com o sufixo .test.js ou .spec.js. Isso mantém o teste perto do código e facilita encontrar. Evite uma pasta __tests__ separada.

Como evoluir a estrutura conforme o projeto cresce?

Comece simples: src/features/, src/shared/, src/assets/. Conforme novas funcionalidades surgem, crie novas pastas dentro de features/. Não tente prever tudo no início - refatore quando sentir dor.