Como hospedar um app React (build, rotas e domínio)

Um app React feito com Vite não roda no servidor: ele vira uma pasta de arquivos (um index.html, JavaScript, CSS e imagens) e o navegador executa o React. Hospedar, então, é publicar essa pasta em algum lugar que a entregue por HTTPS. Dá para fazer isso em poucos minutos, mas dois detalhes derrubam muita gente: as rotas que dão 404 ao recarregar e as variáveis de ambiente que "somem" ou vazam.

Os exemplos usam o Vite, uma das ferramentas de build que a documentação do React indica para quem monta o próprio projeto. O Create React App foi descontinuado para apps novos em fevereiro de 2025.

O que você precisa antes de começar?#

• Uma versão recente do Node.js, que atenda ao mínimo pedido na documentação do Vite.
• Um projeto React com Vite. Para criar um do zero:

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

O -- antes de --template é necessário no npm 7 ou superior. Use --template react-ts se quiser TypeScript. O npm run dev abre o servidor de desenvolvimento, que serve só para você programar e não vai para produção.

Como gerar o build de produção?#

npm run build
npm run preview

O build roda vite build e escreve tudo em dist/, minificado. O preview serve dist/ em http://localhost:4173 para você conferir o resultado. A documentação do Vite avisa que o preview não é um servidor de produção.

A pasta dist/ é o que você publica. Seu código-fonte, o node_modules e os arquivos .env ficam de fora. Se o site vai ficar em um subcaminho (exemplo.com/app/), defina base: '/app/' no vite.config.js. Em domínio próprio ou subdomínio, o padrão '/' está certo.

Por que as rotas dão 404 ao recarregar a página?#

Com React Router em modo navegador, a URL /sobre só existe dentro do JavaScript:

import { createBrowserRouter, RouterProvider } from "react-router";

const router = createBrowserRouter([
  { path: "/", element: <Home /> },
  { path: "/sobre", element: <Sobre /> },
]);

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

Clicar em um link funciona, porque o navegador não pede nada ao servidor. Ao recarregar /sobre, porém, ele pede esse caminho ao servidor, que procura um arquivo sobre, não encontra e responde 404. O servidor precisa devolver o index.html para todo caminho que não é um arquivo, e deixar o React Router decidir a tela.

Cada servidor faz isso de um jeito. No Firebase Hosting, por exemplo, é uma regra de rewrites em firebase.json apontando ** para /index.html. No Nginx, é try_files $uri /index.html;. Se o seu servidor não tem essa regra, as rotas profundas quebram. O mesmo vale para uma SPA gerada pelo modo framework do React Router com ssr: false em react-router.config.ts.

Para páginas que precisam de SEO e conteúdo já no primeiro carregamento, uma SPA pura é limitada: veja SSR, SSG e site estático e como hospedar um app Next.js.

Como usar variáveis de ambiente no React?#

O Vite só expõe ao código as variáveis com prefixo VITE_, lidas por import.meta.env. No arquivo .env.production:

VITE_API_URL=https://api.exemplo.com

const res = await fetch(`${import.meta.env.VITE_API_URL}/produtos`);

O valor é gravado no JavaScript durante o build. Mudar a variável depois exige um novo build, e qualquer visitante pode ler o valor no código da página. Por isso, a documentação do Vite diz que VITE_* não deve guardar dados sensíveis como chaves de API. Segredos ficam em um backend (veja como hospedar uma API), e o front-end chama esse backend. Para o conceito geral, leia o que são variáveis de ambiente.

Como publicar a pasta dist?#

O caminho depende de onde você hospeda, mas o princípio é o mesmo: enviar o conteúdo de dist/ (não a pasta em si) para um servidor estático, com o index.html na raiz. Confira antes de publicar:

1. npm run build terminou sem erro.
2. npm run preview abre o app e a navegação entre rotas funciona.
3. O fallback para index.html está configurado no servidor.
4. Nenhum .env nem segredo foi parar em dist/, porque tudo ali é público.

Depois do deploy, abra uma rota profunda direto na barra de endereço (por exemplo, /sobre) e recarregue. Se carregar, o fallback está certo. Para entender o ciclo completo, veja o que é deploy e como hospedar um site.

Como colocar um domínio próprio?#

Depois que o app responde no endereço do provedor, aponte seu domínio para ele com registros DNS, os que o provedor indicar (em geral um CNAME para subdomínios como www). O HTTPS costuma ser emitido automaticamente depois que o DNS propaga. O passo a passo está em como apontar um domínio para o seu app e como usar um domínio personalizado.

Quais são os erros comuns?#

• Tela branca em produção: o base do Vite está errado para o endereço onde o site fica, e os arquivos de /assets dão 404. Abra o console do navegador e a aba Rede.
• 404 ao recarregar: falta o fallback para index.html, como explicado acima.
• import.meta.env.VITE_X é undefined: a variável não tem o prefixo VITE_, ou foi definida depois do build.
• Site antigo depois de publicar: o navegador ou a CDN guardou o index.html em cache. Os arquivos em assets/ levam um hash no nome, então só o index.html deve ter cache curto. Veja o que é Cache-Control.

Como fazer isso na Square Cloud#

O app React com Vite roda no runtime de sites estáticos da Square Cloud. Você roda npm run build e envia o conteúdo de dist/ em um ZIP pelo painel; a CLI, o GitHub e a extensão do VS Code são as outras formas de deploy.

Para o fallback das rotas, renomeie dist/index.html para vite.html antes de compactar: o runtime estático responde com o vite.html a todo caminho que não é um arquivo, então recarregar /sobre funciona. O passo a passo está no tutorial de React da documentação.

O arquivo de configuração squarecloud.app é opcional: o painel o gera no deploy com o arquivo principal e a memória, ou você mesmo o escreve na raiz do projeto. Sites precisam de pelo menos 512 MB de RAM.

Toda aplicação web ganha um subdomínio *.squareweb.app com HTTPS, em qualquer plano. O domínio próprio entra a partir do Standard: você cria no seu registrador os registros DNS que o painel mostra, e o TLS é automático. O domínio continua registrado em seu nome. Os planos são cobrados em reais, e o Hobby começa em R$ 12,49 por mês. Para mais detalhes, veja domínios e hospedagem de sites.