Base de Conhecimento

React na VPS: como publicar seu app com Nginx

  • react, vps, nginx, vite, deploy
  • Usuários acharam útil: 0

Do build do Vite ao server block do Nginx: como levar um app React de página única para um servidor próprio, sem segredo no front e com uma regra para as rotas do app.

Por Redação Eleven Host · @robson.direitodigital · 21 de novembro de 2026 · 9 min de leitura

Arte da Eleven Host: janela de terminal com o título: React na VPS: como publicar seu app com Nginx

Capa da Redação Eleven Host para o guia: React na VPS: como publicar seu app com Nginx Arte: Eleven Host

Publicar React na VPS é gerar o build do app, que vira um conjunto de arquivos estáticos, copiar essa pasta para o servidor e deixar o Nginx entregar os arquivos, com uma regra que manda as rotas do app para o index.html.

Um app React feito com Vite vira, no build, arquivos HTML, JavaScript e CSS. O servidor só precisa entregar esses arquivos; o ponto de atenção é a regra que devolve o index.html para as rotas do app, senão um endereço interno aberto direto pode dar erro 404.

O que é publicar um app React numa VPS

Um app React de página única, o SPA, carrega uma única página HTML e vai atualizando o conteúdo conforme a pessoa usa. A documentação do React explica que esse é o formato com que as ferramentas de build começam: só no navegador, sem rotas, busca de dados nem estilos prontos.

Na prática, o código que você escreve passa por uma ferramenta de build, que junta tudo em arquivos prontos para a web. Esses arquivos não dependem de um programa rodando no servidor; um servidor web os entrega. É aqui que entra a VPS, um servidor virtual. O que é e como escolher uma está em O que é servidor VPS: guia simples para iniciantes.

Para criar um app novo, a página do React recomenda começar com um framework, como Next.js, React Router ou Expo. Ela lembra que esses frameworks também geram apps de página única ou páginas estáticas.

Começar do zero com uma ferramenta de build é a outra saída, para quem tem restrições que os frameworks não atendem, quer montar o próprio framework ou quer aprender o básico. A documentação cita Vite, Parcel e Rsbuild, e avisa que, nesse caminho, rotas e busca de dados ficam por sua conta.

E o Create React App?

Num post de 14/02/2025, o time do React anunciou a descontinuação do Create React App para apps novos: quem instala vê um aviso. Os apps existentes continuam funcionando em modo de manutenção.

Quando faz sentido usar uma VPS

Recomendamos considerar uma VPS quando o app React já vai conviver com outras coisas no mesmo servidor, como uma API, um painel interno ou outros sites, ou quando você quer controlar a configuração do servidor web. Para um app só estático e sem mais nada, uma hospedagem estática também é uma opção que a própria documentação do React menciona.

Catálogo de VPS da Eleven Host: seis planos, do Bronze ao Titanium. VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver VPS

O que você precisa antes de começar

Em 21/11/2026, a versão mais recente do React publicada no npm era a 19.3.1, e a do Vite, a 8.3.8. Pelo registro do pacote no npm, essa versão do Vite pede Node.js 20.19 ou mais novo na linha 20, ou 22.12 em diante.

Em geral, o Node.js é usado só no computador em que o build é gerado. Recomendamos gerar o build na sua máquina e mandar para a VPS apenas a pasta pronta: assim o servidor só entrega arquivos e não precisa de Node.js.

Do lado do servidor, a página do Certbot pede acesso SSH com um usuário sudo; para o HTTPS no fim, recomendamos ter um domínio.

Como gerar o build do React com Vite

A documentação do React mostra este comando para criar um projeto com Vite e TypeScript:

npm create vite@latest my-app -- --template react-ts

Pela documentação do Vite, o build sai com:

npm run build

No package.json do projeto, esse script corresponde a "build": "vite build". O Vite usa o index.html da raiz como entrada e grava o resultado na pasta dist, que pode ser trocada pela opção build.outDir.

Para ver o resultado antes de publicar, existe o npm run preview, que roda o vite preview na porta 4173 por padrão. A documentação do Vite avisa que ele serve para olhar o build localmente e não foi feito para ser servidor de produção.

Se o app usa o React Router em modo framework com ssr: false, a documentação do React Router indica publicar a pasta build/client, e não a dist.

Variáveis de ambiente: nada de segredo no front

No Vite, as variáveis ficam em import.meta.env e são trocadas pelo valor no momento do build. Só as que começam com VITE_ chegam ao código que vai para o navegador.

A documentação do Vite diz que variáveis VITE_ não devem conter informação sensível, como chaves de API, porque o valor fica dentro dos arquivos publicados. Senha de banco e token de pagamento ficam num backend, fora do app React.

O Vite lê os arquivos .env e .env.local e, para cada modo, .env.[mode] e .env.[mode].local. O build roda no modo production; para outro modo, um exemplo da doc:

vite build --mode staging

App numa subpasta do domínio

Se o app vai morar num caminho como exemplo.com.br/painel/, e não na raiz, o Vite pede a opção base na configuração, para os caminhos dos arquivos serem reescritos. A opção também pode ir na linha de comando, como no exemplo da documentação:

vite build --base=/my/public/path/

O exemplo de Nginx mais abaixo considera o app na raiz do domínio.

Como instalar o Nginx na VPS

O Nginx vem antes do arquivo de configuração do app. Um exemplo de comando para Ubuntu ou Debian, pelo pacote da distribuição, para conferir no seu servidor:

sudo apt update

sudo apt install nginx

Para testar a configuração, a documentação do Nginx indica:

sudo nginx -t

Como levar os arquivos para a VPS

A pasta de destino precisa existir antes da cópia. Um exemplo de comando na VPS, trocando usuario pelo seu usuário:

sudo mkdir -p /var/www/meuapp

sudo chown usuario:usuario /var/www/meuapp

Do seu computador, dentro da pasta do projeto, um exemplo de envio com rsync; a barra no fim de dist/ manda o conteúdo da pasta, e não a pasta em si:

rsync -av dist/ usuario@seu-servidor:/var/www/meuapp/

Um programa de SFTP também resolve: o importante é que o index.html fique direto em /var/www/meuapp. A documentação do Vite lembra que, depois de uma nova publicação, arquivos antigos podem ser apagados, então recomendamos copiar a pasta inteira gerada pelo último build.

Como criar o server block com try_files

Com o Nginx instalado e os arquivos no lugar, falta o server block. Pela documentação do Nginx, a diretiva root define a pasta de onde saem os arquivos, index define o arquivo de entrada (o padrão é index.html) e try_files confere os arquivos na ordem, usando o primeiro que existir; se nenhum existir, faz um redirecionamento interno para o último item.

É esse último item que resolve as rotas do React. A documentação do React Router explica que o servidor precisa mandar todas as URLs para o index.html do build, e que erro 404 em rota válida provavelmente indica servidor sem essa regra. Um exemplo de arquivo, em /etc/nginx/conf.d/meuapp.conf, para conferir no seu servidor:

server {

listen 80;

server_name exemplo.com.br www.exemplo.com.br;

root /var/www/meuapp;

index index.html;

location / {

try_files $uri $uri/ /index.html;

}

location = /index.html {

add_header Cache-Control "no-cache";

}

}

No pacote do Ubuntu, a configuração também pode ficar em sites-available, com um link em sites-enabled; confira qual pasta o nginx.conf do seu servidor inclui. Depois de salvar, teste e recarregue:

sudo nginx -t

sudo nginx -s reload

Cache dos arquivos do build

O build do Vite gera arquivos com hash no nome para JavaScript, CSS e imagens. Para o HTML, a documentação do Vite recomenda o cabeçalho Cache-Control: no-cache, para o navegador não continuar abrindo um index.html que aponta para arquivos que já saíram. O bloco location = /index.html do exemplo serve para isso.

Como funciona o cache do navegador e como configurar está em Cache do navegador: o que é e como configurar no site. A compressão dos arquivos de texto é outro ajuste do Nginx, explicado em Compressão gzip: o que é e como ativar no site.

HTTPS com Certbot

Antes do certificado, recomendamos apontar o domínio para a VPS. A página do Certbot pede que o site esteja acessível pela internet por HTTP, na porta 80. A página também pede remover antes um Certbot instalado pelo apt. Os comandos que ela mostra para Nginx com snap:

sudo snap install --classic certbot

sudo ln -s /snap/bin/certbot /usr/local/bin/certbot

sudo certbot --nginx

O certbot --nginx obtém o certificado e edita a configuração do Nginx. Para testar a renovação automática, a página indica:

sudo certbot renew --dry-run

Checklist do React na VPS

  • build gerado com npm run build e pasta dist (ou build/client) conferida;
  • nenhum segredo em variável VITE_;
  • opção base ajustada se o app ficar numa subpasta;
  • Nginx instalado e nginx -t sem erro;
  • pasta /var/www/meuapp criada antes da cópia;
  • index.html direto na raiz da pasta;
  • server block com try_files apontando para /index.html;
  • rota interna aberta direto no navegador sem 404;
  • domínio apontado antes do Certbot.

Uma nota com os caminhos do projeto

Recomendamos anotar a pasta do build, o arquivo do server block e a data de cada publicação.

Ao lado da VPS, também há registro de domínio na Eleven Host. Buscar domínio

Perguntas frequentes

Preciso de Node.js na VPS para publicar React?

Para um app de página única, não necessariamente: o build pode ser gerado no seu computador, e a VPS só entrega os arquivos com o Nginx. Node.js na VPS entra se você quiser gerar o build lá ou rodar uma API.

Por que a rota do app dá 404 quando atualizo a página?

O servidor está procurando um arquivo com aquele caminho. No exemplo de server block acima, a regra try_files com /index.html no fim manda essas rotas para o app, que é o que a documentação do React Router diz que o servidor precisa fazer.

Posso usar o vite preview no servidor?

A documentação do Vite diz que ele serve para ver o build localmente e não foi feito para produção.

O Create React App ainda funciona?

Para apps existentes, segue em modo de manutenção. Para apps novos, o time do React o descontinuou em 14/02/2025 e recomenda um framework ou uma ferramenta de build como o Vite.

Esta resposta lhe foi útil?

Artigos Relacionados