Montar um projeto React do zero pode parecer um processo cheio de etapas. Mas com o guia certo, você sai do zero para uma tela rodando em poucos minutos. Este passo a passo cobre o setup inicial, desde os pré-requisitos até o primeiro componente, sem pular detalhes que costumam travar quem está começando.
Para este setup, você vai precisar de: Node.js instalado (versão LTS recomendada) e um editor de código, como VS Code. O resultado esperado é um projeto React rodando em http://localhost:3000 (ou outra porta), com um componente simples sendo exibido.
Passo 1: Instalar o Node.js
O Node.js é o ambiente que executa o JavaScript fora do navegador. Ele vem com o npm, gerenciador de pacotes usado para instalar o React e outras dependências. Para verificar se já está instalado, abra o terminal e digite node -v. Se aparecer a versão (ex.: v20.11.0), você está pronto. Caso contrário, baixe o instalador no site oficial e siga as instruções.
Erro comum: usar uma versão muito antiga do Node. Isso pode gerar conflitos de compatibilidade com pacotes recentes. Prefira sempre a versão LTS mais atual.
Passo 2: Criar o projeto com Create React App ou Vite
Existem duas rotas principais para criar um projeto React. A mais tradicional é o Create React App:
npx create-react-app meu-app
Esse comando cria uma pasta com toda a estrutura pronta. A alternativa moderna é o Vite, que entrega um projeto mais leve e com inicialização mais rápida:
npm create vite@latest meu-app -- --template react
O Vite pergunta qual template usar. Escolha react (sem TypeScript) ou react-ts, se preferir TypeScript.
Dica: o Create React App é oficial e estável, mas o Vite vem ganhando espaço pela velocidade. Se você quer um projeto enxuto, vale testar o Vite.
Passo 3: Instalar as dependências e rodar o servidor
Com o projeto criado, entre na pasta:
cd meu-app
Agora instale as dependências. No Create React App, elas já vêm instaladas. No Vite, rode npm install. Depois, inicie o servidor de desenvolvimento:
npm start
Para o Vite, o comando é npm run dev. O terminal mostra o endereço local. Abra no navegador e você verá a página padrão do React.
Erro comum: esquecer de rodar npm install no Vite antes de npm run dev. Sem as dependências, o comando falha com mensagem de módulo não encontrado.
Passo 4: Entender a estrutura de pastas
Repare na pasta src. É ali que fica o código do seu app. O arquivo App.js é o componente principal. O index.js (ou main.jsx no Vite) é o ponto de entrada que renderiza o React no HTML.
Abra o App.js e altere o texto padrão para algo como <h1>Olá, React!</h1>. Salve e veja a atualização automática no navegador, o chamado hot reload.
Dica: não edite os arquivos da raiz, como package.json, sem entender o que está mudando. A estrutura padrão já funciona para começar.
Passo 5: Criar seu primeiro componente
Dentro de src, crie um arquivo chamado Saudacao.js. Escreva uma função que retorna JSX:
function Saudacao() { return <p>Meu primeiro componente</p>; }
export default Saudacao;
Importe esse componente no App.js:
import Saudacao from './Saudacao';
E use no JSX: <Saudacao />. Salve e veja o texto aparecer na tela.
Erro comum: esquecer o export default. Sem ele, o import falha com erro de sintaxe.
Checklist do que foi feito
- Node.js instalado e verificado com
node -v. - Projeto criado com Create React App ou Vite.
- Dependências instaladas e servidor de desenvolvimento rodando.
- Estrutura de pastas entendida (pasta
srccomo coração do app). - Primeiro componente criado e importado com sucesso.
Com esse setup, você tem a base para evoluir. O próximo passo natural é aprender sobre estado com useState ou dividir a interface em mais componentes. Reaproveite essa estrutura para seus próximos projetos.
FAQ
Preciso instalar o React separadamente?
Não. Tanto o Create React App quanto o Vite já incluem o React nas dependências do projeto. Depois de criar o projeto, o React está disponível para uso imediato.
Qual a diferença entre Create React App e Vite?
O Create React App é a ferramenta oficial do Facebook, com configuração pronta e ampla documentação. O Vite é mais rápido no desenvolvimento e gera builds menores. Para projetos simples, ambos funcionam bem. A escolha depende da preferência por velocidade (Vite) ou por tradição (CRA).
O que fazer se o comando npm start não funcionar?
Verifique se o Node.js está na versão LTS. Depois, confirme se você está no diretório correto do projeto e se as dependências foram instaladas com npm install. Erros de porta também são comuns, tente mudar a porta no terminal.
Posso usar TypeScript no setup inicial?
Sim. No Create React App, use npx create-react-app meu-app --template typescript. No Vite, escolha o template react-ts. O resto do fluxo é igual, mas os arquivos usam extensão .tsx.
Preciso de um servidor backend para rodar React?
Não. O React roda no navegador e o servidor de desenvolvimento é apenas para servir os arquivos. Integração com backend é um passo posterior, quando você precisar de dados dinâmicos.
O que é JSX e por que ele parece HTML?
JSX é uma sintaxe que mistura JavaScript e marcação. Ele parece HTML, mas permite escrever expressões JavaScript dentro de chaves. O React transforma JSX em elementos de UI. Não é obrigatório, mas é o padrão na maioria dos projetos.