Estruturar projeto React: guia do zero ao deploy

Quando um desenvolvedor decide montar um projeto React do zero, a tentação de largar tudo no src/ e sair codando é grande. O resultado, semanas depois, é uma pasta com 47 arquivos soltos, imports relativos bizarros (../../../components) e a sensação de que qualquer alteração quebra algo. Estruturar um projeto React não é sobre seguir uma receita mágica, é sobre criar limites claros entre responsabilidades. Este guia percorre as etapas para montar uma base que escala sem dor de cabeça, do npm init ao deploy.

Pré-requisitos

• Node.js 18+ instalado
• Familiaridade básica com JSX e componentes funcionais
• Um editor de código (VS Code, WebStorm)

Passo 1: Escolher o bundler e iniciar o projeto

O create-react-app (CRA) foi durante anos o ponto de partida padrão, mas perdeu tração: builds lentos, configuração engessada, dependências pesadas. Hoje, duas alternativas dominam: Vite (para SPAs puras) e Next.js (para apps que precisam de SSR/SSG).

Vite é a escolha mais enxuta para projetos que não exigem renderização no servidor. Inicie com:

npm create vite@latest meu-app -- --template react cd meu-app npm install

Next.js é indicado quando há necessidade de SEO, rotas dinâmicas ou dados que vêm de uma API externa. Inicie com:

npx create-next-app@latest meu-app

Erro comum a evitar: não instale bibliotecas de roteamento (React Router) em projetos Next.js, ele já tem sistema de rotas baseado em arquivos.

Passo 2: Definir a estrutura de pastas

A organização de pastas no React não precisa ser complexa, mas deve seguir um princípio: cada pasta tem uma responsabilidade única. A estrutura recomendada para projetos de médio porte:

src/ ├── components/ # Componentes reutilizáveis (Button, Card, Modal) ├── pages/ # Componentes que representam rotas (Home, About, Dashboard) ├── hooks/ # Custom hooks (useAuth, useFetch, useDebounce) ├── utils/ # Funções puras auxiliares (formatDate, validateEmail) ├── services/ # Chamadas a APIs (apiClient, endpoints) ├── styles/ # Arquivos CSS globais ou tokens de tema ├── contexts/ # Contextos React (AuthContext, ThemeContext) └── assets/ # Imagens, fontes, SVGs estáticos

Dica prática: se um componente só é usado em uma página, coloque-o dentro da pasta da página (pages/Home/Header.jsx), não em components/. Isso reduz o escopo e evita poluição.

Erro comum a evitar: criar pastas containers/ e presentational/, essa separação caiu em desuso com hooks. Prefira a divisão por funcionalidade.

Passo 3: Configurar o roteamento

Com Vite, instale o React Router DOM:

npm install react-router-dom

Crie um arquivo src/router.jsx que centraliza todas as rotas:

import { createBrowserRouter, RouterProvider } from 'react-router-dom'; import Home from './pages/Home'; import About from './pages/About'; import NotFound from './pages/NotFound';

const router = createBrowserRouter([ { path: '/', element: <Home /> }, { path: '/about', element: <About /> }, { path: '*', element: <NotFound /> }, ]);

export default function AppRouter() { return <RouterProvider router={router} />; }

No main.jsx, substitua <App /> por <AppRouter />.

Erro comum a evitar: não coloque lógica de busca de dados dentro dos componentes de rota. Use loader (React Router 6.4+) ou hooks separados.

Passo 4: Gerenciar estado global com contexto

Nem todo estado precisa ir para o Redux. Para temas, autenticação ou preferências do usuário, o Context API é suficiente. Crie um contexto em src/contexts/ThemeContext.jsx:

import { createContext, useContext, useState } from 'react';

const ThemeContext = createContext();

export function ThemeProvider({ children }) { const [theme, setTheme] = useState('light'); return ( <ThemeContext.Provider value={{ theme, setTheme }}> {children} </ThemeContext.Provider> ); }

export function useTheme() { const context = useContext(ThemeContext); if (!context) throw new Error('useTheme must be used within ThemeProvider'); return context; }

Envolva a aplicação com o provider no main.jsx.

Dica prática: se o estado precisar ser persistido (ex.: tema escolhido), combine o contexto com localStorage dentro do provider.

Passo 5: Configurar o build e variáveis de ambiente

O Vite já vem com otimizações de build embutidas, mas é preciso configurar variáveis de ambiente para ambientes diferentes (dev, staging, production).

Crie um arquivo .env na raiz:

VITE_API_URL=http://localhost:3000/api

No código, acesse com import.meta.env.VITE_API_URL. Para produção, crie .env.production:

VITE_API_URL=https://api.meuapp.com

Erro comum a evitar: não coloque chaves secretas (API keys de serviços externos) em variáveis de ambiente do front-end, elas ficam expostas no bundle. Use um backend proxy ou serverless functions.

Passo 6: Configurar o deploy

O deploy de um projeto React pode ser feito em serviços como Vercel, Netlify ou Cloudflare Pages. O processo é semelhante:

1. Conecte o repositório (GitHub, GitLab) ao serviço.
2. Configure o comando de build: npm run build.
3. Defina o diretório de saída: dist (Vite) ou .next (Next.js).
4. Configure variáveis de ambiente no painel do serviço.
5. Ative deploy automático a cada push na branch principal.

Para Vite com Vercel: o vercel.json pode ser:

{ "rewrites": [{"source": "/(.*)", "destination": "/index.html"}] }

Isso garante que rotas do React Router funcionem após o deploy.

Dica prática: antes de deployar, teste o build localmente com npm run build e depois npx serve dist para simular o ambiente de produção.

Checklist rápido

• [ ] Bundler escolhido (Vite ou Next.js)
• [ ] Estrutura de pastas definida (components, pages, hooks, utils, services)
• [ ] Roteamento configurado (React Router ou file-based)
• [ ] Contextos criados para estado global
• [ ] Variáveis de ambiente configuradas (.env, .env.production)
• [ ] Build testado localmente
• [ ] Deploy configurado com CI/CD automático

FAQ

Qual a diferença entre Vite e Next.js para estruturar um projeto React?

Vite é um bundler focado em front-end puro, ideal para SPAs que não precisam de renderização no servidor. Next.js é um framework full-stack que adiciona SSR, SSG e rotas baseadas em arquivos. Escolha Vite para apps simples ou dashboards; Next.js para sites com SEO ou conteúdo dinâmico.

Devo usar src/ ou app/ como pasta principal?

Ambas funcionam, mas src/ é o padrão consolidado na comunidade React. Next.js 13+ usa app/ para o novo sistema de rotas, mas ainda aceita src/ como alternativa. Para projetos com Vite, mantenha src/.

Como organizar componentes que são usados em várias páginas?

Coloque-os na pasta src/components/. Se um componente for usado em mais de três páginas, considere extraí-lo para um pacote separado ou uma biblioteca interna (src/lib/).

É necessário usar TypeScript desde o início?

Não, mas é altamente recomendado para projetos que vão crescer. TypeScript reduz erros de tipo e melhora a documentação do código. Tanto Vite quanto Next.js têm templates com TypeScript.

Como lidar com imports relativos muito longos?

Configure aliases no vite.config.js:

export default defineConfig({ resolve: { alias: { '@': path.resolve(__dirname, './src'), }, }, });

Agora você pode importar com import Button from '@/components/Button'.

O que fazer se o build falhar no deploy?

Verifique três pontos: 1) as variáveis de ambiente estão definidas no serviço de deploy, 2) o comando de build está correto, 3) o diretório de saída está apontado certo (dist para Vite, .next para Next.js). Teste o build localmente antes de deployar.