Organização de pastas no React: estruture seu projeto de forma escalável

Faaaaala, Dev! Se você está começando a sua jornada em React e já se deparou com aquela bagunça de pastas e arquivos, segura firme, porque este artigo vai te ajudar a transformar essa confusão em uma estrutura organizada e escalável. Aqui, vamos explorar, de forma prática e direta, como organizar a estrutura de pastas no React para deixar seu código mais limpo e fácil de manter. Preparado? Bora codar!

Por que a estrutura de pastas é importante no React?

Imagine que você está construindo uma aplicação simples e tudo parece estar sob controle. Mas conforme a aplicação cresce, o número de arquivos aumenta e, sem uma organização adequada, você acaba perdendo tempo procurando componentes, estilos, hooks e contextos. Uma estrutura de pastas bem planejada é como uma “mão amiga” que te guia e mantém o projeto sustentável ao longo do tempo. E isso, meu amigo dev, faz uma diferença e tanto!

Passo 1: o básico do básico

A primeira estrutura que encontramos em projetos pequenos é bem minimalista. Normalmente, você inicia com uma pasta src e um único arquivo App.js que contém o componente principal.


src/
└── App.js

Essa é uma ótima forma de começar, principalmente se você está apenas explorando os primeiros conceitos de React. Porém, se a sua aplicação cresce e você continua colocando tudo em App.js, a experiência de manutenção vai ficar muito complicada.

Passo 2: evoluindo para múltiplos arquivos

Logo, você perceberá que ter tudo em um único arquivo é insustentável. A primeira melhoria é separar os componentes em arquivos diferentes, criando uma estrutura modular e mais fácil de entender. Suponha que você tenha uma lista e cada item seja um componente individual. Aqui está uma estrutura de exemplo para isso:


src/
├── App.js
├── List.js
└── ListItem.js

Essa abordagem é prática e suficiente para pequenos projetos, onde cada componente pode ser mantido em seu próprio arquivo. Com essa estrutura, a manutenção fica mais fácil e o código mais legível.

Exemplo prático

Imagine que App.js seja a lista principal e List.js e ListItem.js representem uma lista e seus itens. Isso pode ajudar a ter uma visão clara da função de cada arquivo:


// ListItem.js
const ListItem = ({ item }) => (
  <li>{item.name}</li>
);

export default ListItem;


// List.js
import ListItem from './ListItem';

const List = ({ items }) => (
  <ul>
    {items.map((item) => (
      <ListItem key={item.id} item={item} />
    ))}
  </ul>
);

export default List;


// App.js
import List from './List';

const items = [{ id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2' }];

function App() {
  return (
    <div>
      <h1>Minha Lista</h1>
      <List items={items} />
    </div>
  );
}

export default App;

Passo 3: separando componentes em pastas próprias

Conforme o projeto evolui, separar os componentes em pastas próprias faz todo sentido. Cada pasta pode conter o componente em si e arquivos relacionados, como estilos e testes. Isso facilita na organização e torna os arquivos fáceis de encontrar.


src/
├── components/
│   ├── App/
│   │   ├── App.js
│   │   ├── App.test.js
│   │   └── App.css
│   └── List/
│       ├── List.js
│       ├── ListItem.js
│       └── List.css

Assim, cada pasta é uma “cápsula” de funcionalidade e responsabilidade, contendo apenas os arquivos necessários para aquele componente.

Passo 4: componentes genéricos e específicos

Para projetos maiores, separar componentes genéricos e reutilizáveis dos componentes específicos faz toda a diferença. Componentes como botões, inputs e modais podem ficar em uma pasta components, enquanto componentes específicos, como formulários de autenticação, ficam em features.


src/
├── components/
│   ├── Button/
│   └── Input/
├── features/
│   ├── Auth/
│   │   ├── Login.js
│   │   └── Register.js
└── services/
    └── api.js

Essa estrutura permite que componentes e funções reutilizáveis sejam facilmente acessados, enquanto os específicos permanecem organizados em suas funcionalidades.

Exemplo: componente de botão e formulário de login

Com a estrutura acima, você pode ter um botão reutilizável para várias partes da aplicação e um formulário de login específico para a funcionalidade de autenticação.


// Button.js
const Button = ({ children, onClick }) => (
  <button onClick={onClick}>{children}</button>
);

export default Button;


// Login.js
import Button from '../../components/Button';

const Login = () => {
  return (
    <form>
      <input type="text" placeholder="Usuário" />
      <input type="password" placeholder="Senha" />
      <Button>Entrar</Button>
    </form>
  );
};

export default Login;

Passo 5: estrutura para contextos, hooks e serviços

Conforme o projeto cresce ainda mais, você começa a usar Context API e hooks customizados para lidar com estados e lógicas específicas. É importante separar esses recursos em pastas próprias para manter o código mais organizado.


src/
├── components/
│   └── Button/
├── context/
│   └── AuthContext.js
├── features/
│   └── Auth/
│       ├── Login.js
│       └── Register.js
├── hooks/
│   ├── useAuth.js
│   └── useFetch.js
└── services/
    └── api.js

Essa estrutura oferece uma separação clara:

context/ mantém os contextos para estados globais, como AuthContext.js.

hooks/ mantém a lógica customizada reutilizável.

services/ centraliza as chamadas API.

Explicação:

Contextos globais: armazene contextos que gerenciam estados compartilhados em toda a aplicação na pasta src/context/. Isso facilita o acesso e a manutenção desses estados.

Contextos específicos: se um contexto for muito específico de uma funcionalidade e não for usado em outras partes da aplicação, você pode optar por mantê-lo dentro da pasta da feature correspondente. No entanto, para fins de clareza e padronização, recomendamos centralizar os contextos em src/context/.

Passo 6: usando arquivos `index.js` para facilitar importações

Um truque prático para melhorar a legibilidade do código e organizar as importações é o uso de arquivos index.js dentro de cada pasta de componentes e também na pasta components/. Eles funcionam como pontos de exportação, simplificando as importações em outros arquivos.

Dentro do componente:


// src/components/Button/index.js
export { default as Button } from './Button';

Na pasta components/:


// src/components/index.js
export { Button } from './Button';
// Exporte outros componentes conforme necessário

Assim, ao importar o componente em outro arquivo, você pode fazer de forma mais direta:


import { Button } from './components';

Isso torna suas importações mais organizadas e o código mais limpo, especialmente em projetos com muitos componentes. O uso de arquivos index.js centraliza as exportações, facilitando o acesso aos componentes sem precisar especificar caminhos complexos.

Passo 7: simplificando importações com caminhos absolutos

Conforme seu projeto cresce, lidar com importações relativas pode se tornar um desafio. Felizmente, podemos configurar nosso projeto para usar caminhos absolutos, facilitando as importações e evitando confusões.

Configurando o `jsconfig.json` (para JavaScript) ou `tsconfig.json` (para TypeScript)

Para projetos em JavaScript, crie um arquivo jsconfig.json na raiz do seu projeto com o seguinte conteúdo:


{
  "compilerOptions": {
    "baseUrl": "src"
  },
  "include": ["src"]
}

Para projetos em TypeScript, ajuste seu tsconfig.json para incluir o baseUrl:


// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "src",
    // outras configurações
  },
  // outras configurações
}

Essa configuração define a pasta src como o diretório base para as importações. Agora, você pode importar módulos usando caminhos absolutos a partir de src, em vez de caminhos relativos.

Exemplo prático de importação com caminho absoluto

Antes (com caminho relativo):


// src/features/Auth/Login.js
import Button from '../../components/Button';

Depois (com caminho absoluto):


// src/features/Auth/Login.js
import Button from 'components/Button';

Isso torna suas importações mais diretas e o código mais legível, especialmente quando você tem uma estrutura de pastas profunda.

Observações importantes

Certifique-se de que seu bundler ou ferramenta de construção (como Webpack, Vite ou Create React App) suporta a configuração de baseUrl. No Create React App, a configuração do jsconfig.json ou tsconfig.json já é suportada nativamente.

Após configurar o baseUrl, reinicie seu servidor de desenvolvimento para que as mudanças entrem em vigor.

Benefícios de usar caminhos absolutos

Legibilidade: importações mais curtas e claras.

Manutenção: facilita a refatoração e a movimentação de arquivos sem quebrar importações.

Produtividade: reduz erros causados por caminhos relativos complexos.

Passo 8: gerenciando estilos com CSS Modules ou Styled Components

A maneira como você lida com os estilos em um projeto React pode influenciar significativamente a organização das pastas e a escalabilidade do seu código.

CSS Modules

Os CSS Modules permitem que você escreva estilos em arquivos .module.css, que são escopados localmente por padrão. Isso significa que as classes CSS definidas em um componente não afetarão outros componentes, evitando conflitos de nomenclatura.

Estrutura de pastas com CSS Modules:


src/
├── components/
│   ├── Button/
│   │   ├── Button.js
│   │   └── Button.module.css

Exemplo de uso:


// Button.js
import styles from './Button.module.css';

const Button = ({ children, onClick }) => (
  <button className={styles.button} onClick={onClick}>
    {children}
  </button>
);

export default Button;

Button.module.css


.button {
  background-color: #6200ee;
  color: white;
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
}

Styled Components

Styled Components é uma biblioteca que permite escrever estilos CSS dentro do JavaScript usando o conceito de CSS-in-JS. Os estilos são vinculados diretamente aos componentes, promovendo encapsulamento e facilitando a manutenção.

Instalação:


npm install styled-components

Estrutura de pastas com Styled Components:


src/
├── components/
│   └── Button.js

Exemplo de uso:


// Button.js
import styled from 'styled-components';

const StyledButton = styled.button`
  background-color: #6200ee;
  color: white;
  padding: 8px 16px;
  border: none;
  border-radius: 4px;

  &:hover {
    background-color: #3700b3;
  }
`;

const Button = ({ children, onClick }) => (
  <StyledButton onClick={onClick}>{children}</StyledButton>
);

export default Button;

Impacto na organização das pastas e arquivos

Com CSS Modules:

Os arquivos de estilo (.module.css) ficam próximos aos componentes, mantendo a coesão.
Evita conflitos de nomes de classes, já que os estilos são escopados localmente.

Com Styled Components:

Os estilos são escritos no mesmo arquivo do componente, reduzindo a quantidade de arquivos.
Facilita a reutilização de componentes estilizados e a aplicação de temas.

Vantagens dessas abordagens

Escopo local de estilos: previne que estilos vazem para outros componentes.

Melhor manutenção: estilos e componentes juntos facilitam a leitura e atualização do código.

Reutilização e composição: fácil criação de componentes estilizados reutilizáveis.

Escolhendo a abordagem certa

A escolha entre CSS Modules e Styled Components depende das necessidades do seu projeto e preferências da equipe. Ambas as abordagens são amplamente adotadas e têm suporte ativo na comunidade.

Estrutura de um projeto React (exemplo)

Aqui está um exemplo de estrutura de pastas para um projeto React completo, incluindo pastas para componentes, hooks, contextos, serviços, testes e muito mais. Vamos detalhar cada seção para que você saiba exatamente onde colocar cada tipo de arquivo.


my-rocketseat-app/
├── public/
│   └── index.html
├── src/
│   ├── assets/                  # Imagens e arquivos estáticos
│   ├── components/              # Componentes reutilizáveis
│   │   ├── Button/
│   │   │   ├── Button.js
│   │   │   ├── Button.test.js
│   │   │   └── Button.css
│   │   └── Modal/
│   │       ├── Modal.js
│   │       ├── Modal.test.js
│   │       └── Modal.css
│   ├── context/                 # Contextos para estado global
│   │   └── AuthContext.js
│   ├── features/                # Funcionalidades específicas da aplicação
│   │   ├── Auth/
│   │   │   ├── Login.js
│   │   │   ├── Register.js
│   │   │   └── authSlice.js
│   │   └── Dashboard/
│   │       ├── Dashboard.js
│   │       ├── Dashboard.css
│   │       └── Dashboard.test.js
│   ├── hooks/                   # Hooks personalizados
│   │   ├── useAuth.js
│   │   └── useFetch.js
│   ├── pages/                   # Páginas principais da aplicação
│   │   ├── Home.js
│   │   └── Profile.js
│   ├── services/                # Serviços de API e outras integrações externas
│   │   ├── api.js
│   │   └── authService.js
│   ├── styles/                  # Estilos globais
│   │   ├── variables.css
│   │   └── main.css
│   ├── utils/                   # Utilitários e funções auxiliares
│   │   ├── formatDate.js
│   │   └── slugify.js
│   ├── App.js
│   ├── index.js
│   └── setupTests.js            # Configurações globais para testes
├── .env                         # Variáveis de ambiente
├── package.json
└── README.md

Explicação de cada pasta

assets/: Armazena imagens, ícones e outros arquivos estáticos. Ideal para manter esses arquivos organizados fora do código principal.

components/: Aqui ficam os componentes reutilizáveis e independentes, como botões, modais e outros elementos da interface que podem ser utilizados em várias partes do projeto. Cada componente possui sua própria pasta, incluindo arquivo principal, testes (.test.js) e estilos (.css).

context/: Essa pasta guarda os contextos criados com a Context API do React, úteis para gerenciar estados globais que precisam ser compartilhados entre diferentes componentes. No exemplo, temos o AuthContext.js para autenticação.

features/: Esta pasta é ótima para organizar componentes e lógica específicos de funcionalidades, como “Auth” (autenticação) e “Dashboard” (painel de usuário). Cada funcionalidade tem seus próprios componentes, lógica de estado (como authSlice.js para Redux) e até mesmo estilos e testes próprios.

hooks/: Os hooks personalizados ficam aqui, permitindo o compartilhamento de lógica entre diferentes componentes. Hooks como useAuth.js (para lógica de autenticação) e useFetch.js (para chamadas API) são comuns.

pages/: Contém as páginas principais do aplicativo, como a Home e o Profile. Em frameworks como o Next.js, essa pasta é usada para roteamento automático.

services/: Centraliza as funções que lidam com chamadas de APIs ou serviços externos. Arquivos como api.js e authService.js mantêm o código de integração com serviços separados da lógica dos componentes.

styles/: Para estilos globais da aplicação, como variáveis de CSS ou temas. Inclui arquivos como variables.css e main.css, que afetam toda a aplicação.

utils/: Guarda funções auxiliares e utilitários, como formatDate.js para formatação de datas e slugify.js para transformar textos em slugs. Essas funções são reutilizáveis e independentes dos componentes.

setupTests.js: Configuração global para testes, onde você pode definir configurações para a Testing Library ou outras bibliotecas de teste.

Dicas de organização e boas práticas

Uma estrutura de pastas organizada é essencial para a escalabilidade e a manutenção do código, especialmente em projetos React que tendem a crescer rapidamente. Existem algumas boas práticas para decidir quando criar uma pasta própria para cada tipo de arquivo e quando manter arquivos juntos. Vamos às dicas que vão ajudar a organizar seu projeto de forma eficiente:

1. Quando criar uma pasta para cada tipo de arquivo

Componentes reutilizáveis e isolados: se um componente pode ser utilizado em várias partes do projeto, crie uma pasta dedicada para ele, incluindo arquivos de estilo (.css) e de teste (.test.js). Dessa forma, tudo relacionado ao componente fica em um só lugar, facilitando a manutenção e o reuso.

Hooks e contextos customizados: hooks e contextos que gerenciam lógica complexa ou compartilhada, como autenticação (AuthContext) ou manipulação de dados (useFetch), devem ter suas próprias pastas. Isso facilita a organização e o acesso aos recursos globais da aplicação.

Funcionalidades específicas (features): em projetos maiores, dividir o código por funcionalidades (ex: Auth, Dashboard) permite modularizar a aplicação. Cada funcionalidade tem seus próprios componentes, lógica de estado e até hooks específicos. Isso facilita o desenvolvimento em equipe e a expansão da aplicação.

2. Quando não é necessário criar uma pasta

Componentes pequenos e simples: para componentes menores e usados em apenas uma área específica, não há necessidade de criar uma pasta exclusiva. Você pode colocá-los diretamente na pasta components ou dentro da pasta features se pertencerem a uma funcionalidade específica.

Funções auxiliares únicas: se uma função em utils é muito pequena e usada em poucos lugares, considere mantê-la em um único arquivo utils.js. Caso observe que as funções começam a crescer, então vale a pena separá-las em arquivos próprios, como formatDate.js ou slugify.js.

CSS de componentes internos: caso o componente precise de apenas algumas linhas de CSS, considere manter esses estilos inline ou em um pequeno arquivo .css diretamente na pasta do componente. Evite criar estruturas complexas para componentes com poucos estilos.

3. Modularidade e reutilização

Organize componentes por funcionalidade: à medida que a aplicação cresce, organize componentes específicos em pastas de funcionalidades (features). Isso torna o código mais modular, facilita a manutenção e ajuda novos devs a encontrar facilmente o que precisam.

Prefira componentes reutilizáveis para UI: componentes que serão usados em diferentes partes da aplicação, como botões, inputs e modais, devem ser colocados na pasta components. Isso facilita o compartilhamento e evita a duplicação de código.

Estrutura modular com `index.js` para facilitar importações

Uma boa prática é usar arquivos index.js em pastas de funcionalidades, contextos e hooks. Esses arquivos index.js funcionam como pontos de exportação que agrupam os elementos da pasta e simplificam as importações em outras partes do projeto.

4. Evite aninhamento excessivo

Quanto mais profundo o aninhamento de pastas, mais difícil será navegar pelo projeto. Mantenha a estrutura de pastas o mais plana possível e evite mais do que dois níveis de aninhamento. A simplicidade na organização torna o projeto mais acessível para toda a equipe e facilita a manutenção a longo prazo.

5. Nomeação consistente

Use convenções de nomenclatura consistentes para que os arquivos sejam fáceis de localizar. PascalCase é comumente usado para componentes (Button.js, LoginForm.js), enquanto camelCase é preferido para funções e hooks (useAuth, fetchData). Nomes consistentes ajudam a manter o código organizado e intuitivo para todos os desenvolvedores.

6. Agrupe componentes e arquivos por função

Pense na funcionalidade e nos tipos de componentes que sua aplicação realmente precisa em vez de seguir uma estrutura rígida. Em vez de agrupar por tipo (ex: todos os services em uma pasta), considere agrupar pelo contexto de uso, como features/Auth, que contém todos os arquivos necessários para autenticação (componentes, lógica de estado e hooks).

Conclusão: estruture para escalar

Com esse conhecimento, você está pronto para aplicar boas práticas de organização no seu próximo projeto, deixando o código mais limpo e fácil de manter. Mas e se você quer realmente dominar o React e se tornar um profissional diferenciado no mercado? É aí que entra a formação em React da Rocketseat!

Nesta formação, você vai do básico ao avançado, aprendendo de maneira prática como construir interfaces modernas e reativas, enquanto evolui de verdade na sua carreira. São +64 horas de conteúdo, com 437 aulas gravadas, para você assistir no seu ritmo e aprender o que realmente importa. E não é só teoria! Você coloca a mão na massa em +15 projetos profissionais, enfrenta 113 quizzes e desafios, e ainda ganha um certificado de conclusão validado pelo mercado.

E o suporte? A Rocketseat te acompanha em cada etapa com mentorias individuais, bate-papos em grupo, e até o Café com os Instrutores, para que você tenha respostas e insights diretamente dos especialistas. Tudo isso orientado por Diego Fernandes, cofundador da Rocketseat e expert em JavaScript e React. Com ele, você aprende as tecnologias mais atuais, como ReactJS, Node.js, NextJS, TypeScript, Vite e TailwindCSS.

E tem mais: faça um preview gratuito das aulas e sinta o potencial da formação que pode transformar a sua carreira. Não deixe passar essa chance de se destacar como desenvolvedor React e construir um portfólio de impacto.

🚀

Acesse agora a página da formação em React da Rocketseat e descubra o próximo passo para se tornar um dev de ponta! Até a próxima, e bora codar o futuro!

Lote Final da Black Friday 2024

Encerramento das ofertas de Black Friday! Transforme sua carreira hoje mesmo!

Lote Final da Black Friday 2024

Última chance da Black Friday.

Por que a estrutura de pastas é importante no React?

Passo 1: o básico do básico

Passo 2: evoluindo para múltiplos arquivos

Exemplo prático

Passo 3: separando componentes em pastas próprias

Passo 4: componentes genéricos e específicos

Exemplo: componente de botão e formulário de login

Passo 5: estrutura para contextos, hooks e serviços

Passo 6: usando arquivos index.js para facilitar importações

Passo 7: simplificando importações com caminhos absolutos

Configurando o jsconfig.json (para JavaScript) ou tsconfig.json (para TypeScript)

Exemplo prático de importação com caminho absoluto

Observações importantes

Benefícios de usar caminhos absolutos

Passo 8: gerenciando estilos com CSS Modules ou Styled Components

CSS Modules

Styled Components

Impacto na organização das pastas e arquivos

Vantagens dessas abordagens

Escolhendo a abordagem certa

Estrutura de um projeto React (exemplo)

Explicação de cada pasta

Dicas de organização e boas práticas

1. Quando criar uma pasta para cada tipo de arquivo

2. Quando não é necessário criar uma pasta

3. Modularidade e reutilização

Estrutura modular com index.js para facilitar importações

4. Evite aninhamento excessivo

5. Nomeação consistente

6. Agrupe componentes e arquivos por função

Conclusão: estruture para escalar

Lote Final da Black Friday 2024

Lote Final da Black Friday 2024

Aprenda programação do zero e DE GRAÇA

Passo 6: usando arquivos `index.js` para facilitar importações

Configurando o `jsconfig.json` (para JavaScript) ou `tsconfig.json` (para TypeScript)

Estrutura modular com `index.js` para facilitar importações