Onde hospedar uma SPA em React ou Vite sem quebrar as rotas

Uma aplicação de página única (SPA) em React ou Vite gera, no build, um index.html e alguns arquivos JavaScript e CSS. As telas, as rotas e a navegação acontecem todas dentro do navegador. Funciona bem enquanto o visitante entra pela home e clica nos links. O problema aparece quando ele recarrega /sobre ou abre o endereço direto: o servidor procura um arquivo chamado sobre, não encontra, e responde 404.

Por que a rota quebra

Um site estático responde a cada endereço com um arquivo correspondente. /sobre/index.html existe, então /sobre/ funciona. Uma SPA, porém, não tem um arquivo por tela: a rota /sobre só existe na lógica do React Router. Quando o navegador pede /sobre ao servidor, a resposta precisa ser o mesmo index.html da home. Aí o JavaScript carrega, lê a URL e monta a tela certa.

Sem esse passo, o servidor trata /sobre como arquivo inexistente. O visitante vê uma página de erro em um endereço que, para a aplicação, é válido.

Como o fallback de SPA funciona no Hoster

Ao receber um pedido para <projeto>.hoster.myinfrastructure.click/<caminho>, o Hoster tenta, nesta ordem:

1. Procura o arquivo exato no bucket (<caminho>).

2. Se não achar, tenta o caminho como diretório (<caminho>/index.html).

3. Se ainda não achar e o caminho não tiver extensão, serve o mainFile do projeto, que é o index.html da aplicação.

4. Caminhos com extensão, como .js, .css ou .png, não entram no fallback. Um asset ausente devolve 404 de verdade, o que é o comportamento correto, porque um script faltando precisa aparecer como erro.

Por isso /produtos/42 responde 200 e o React Router monta a tela. Já um /logo.svg que não existe devolve 404, sem ser mascarado pela página inicial.

Há um caso à parte: se o build gerar um 404.html na raiz, o Hoster passa a usá-lo para endereços sem arquivo, com status 404. Isso é útil em sites com páginas estáticas, mas desliga o fallback de SPA. Se a sua aplicação é uma SPA de verdade, não coloque um 404.html na raiz do deploy; deixe o roteamento com o React Router.

O que você precisa conferir

• O --dir da CLI aponta para a pasta do build (dist no Vite), e não para a raiz do repositório.

• O mainFile do projeto é o index.html gerado pelo build.

• Não há 404.html na raiz do deploy, a menos que você queira páginas de erro estáticas.

Variáveis de ambiente sem rebuild

No Vite, import.meta.env.VITE_API_URL é substituído pelo valor no momento do build. Isso significa que o mesmo código apontando para homologação precisa ser refeito para produção. Para o que muda entre ambientes, a alternativa é ler o valor em tempo de execução.

O Hoster injeta, em cada resposta HTML, um bloco antes de </head>:

<script id="hoster-env">
  window.PROCESS_ENV = { "API_URL": "https://api.exemplo.com" };
  window.ENV = window.PROCESS_ENV;
</script>

No código, leia com um fallback:

const API_URL = window.ENV?.API_URL ?? 'http://localhost:3000'

Com o fallback, o mesmo código roda em desenvolvimento, onde a injeção não existe, e em produção. Trocar a variável pelo painel ou pela API vale em até um minuto, na próxima carga do HTML, sem rebuild e sem novo deploy.

Um cuidado: esses valores são públicos e aparecem no HTML servido ao navegador. Não coloque segredo ali.

Cache: quando a mudança aparece

A estratégia de cache controla quanto tempo o navegador e a borda guardam os arquivos. Ela é configurada por projeto, e as três opções principais são estas:

Com balanced, o HTML é revalidado a cada carga, e uma resposta sem mudança volta vazia, com status 304. Arquivos com hash no nome, como index-BosabLVq.js, recebem cache de um ano (immutable), porque o nome muda quando o conteúdo muda.

O cuidado é com extreme: quem já visitou o site pode continuar vendo o HTML antigo por até um mês. Se você costuma publicar correções, use balanced.

Perguntas frequentes

Preciso configurar um arquivo de redirecionamento?

Não. O fallback de SPA já vem ligado. O Hoster não lê arquivos como _redirects ou vercel.json; redirects, rewrites e headers customizados por arquivo de configuração não existem na plataforma.

Por que a home funciona e /sobre não?

A home é o index.html, que existe no bucket. A rota /sobre não é um arquivo, e sem o fallback o servidor responde 404. Depois que o fallback serve o index.html, o React Router cuida do resto.

Mudei uma variável e nada aconteceu. O que houve?

A variável vale na próxima carga do HTML. Se o navegador guardou a página com a estratégia extreme, ele pode seguir com a cópia antiga. Recarregue sem cache ou use balanced.

Para continuar lendo

• Publicar um site estático com HTTPS e domínio próprio

• Liberar e bloquear partes do app pelo plano do usuário

• Guardar dados e arquivos do app sem migration nem credencial de nuvem

Publicar sem montar pipeline

Uma SPA publicada no Hoster precisa de duas coisas: o diretório de build e o mainFile certo. O fallback e o HTTPS já vêm resolvidos; o cache já vem com a estratégia balanced e você pode trocá-la depois, junto com as variáveis. Conhecer o Hoster

Fontes

• Referência do Hoster para pessoas e agentes (llms.txt)

• Página do Hoster