Alojar React, Vue e sites estáticos ligados a APIs externas

Sim, pode alojar um projeto feito com React, Vue ou outro framework JavaScript quando o resultado da compilação for um site estático. O alojamento serve os ficheiros HTML, CSS, JavaScript e imagens já prontos; não precisa de manter o Node.js em execução para os mostrar.

Uma aplicação moderna costuma estar dividida em duas partes:

• Frontend: é compilado com Vite, Webpack, Rollup ou outra ferramenta e gera um diretório como dist, build ou out. Pode compilá-lo na sua conta com Node.js e npm, inclusive dentro do Deploy+, e publicar o resultado normalmente.
• Backend externo: a base de dados, a autenticação ou o armazenamento ficam no Supabase, Firebase, Strapi Cloud, Sanity, Airtable ou qualquer outro fornecedor. O navegador do visitante liga-se à sua API por HTTPS, pelo que esse serviço não é instalado nem executado no alojamento.

O alojamento só tem de ser compatível com aquilo que nele se executa. Uma API externa não exige suporte especial por parte do alojamento.

Duas formas de chamar a API externa

Num frontend completamente estático, a comunicação segue este percurso:

Visitante → HTML, CSS y JS del hosting → API del proveedor

Neste caso, o navegador chama diretamente o fornecedor. A sua API deve aceitar pedidos a partir do seu domínio através de CORS e tem de configurar aí os domínios permitidos e os URL de retorno da autenticação.

Também pode interpor um backend PHP alojado na conta:

Visitante → frontend del hosting → PHP del hosting → API del proveedor

O PHP pode fazer pedidos HTTPS de saída a APIs externas, através de cURL, Guzzle ou do cliente HTTP de frameworks como o Laravel. A API deve estar acessível e permitir a origem de rede, as credenciais e a operação; as suas restrições ou as do servidor podem limitar uma ligação concreta. Esta arquitetura é útil quando precisa de guardar uma chave privada, validar ou transformar os dados antes de os enviar, ou evitar que uma operação sensível seja executada a partir do navegador. O PHP intervém nestes pedidos, mas a API e os seus dados continuam alojados no fornecedor externo.

As restrições CORS do navegador não se aplicam à comunicação entre o PHP e o fornecedor. A API continuará a exigir as suas credenciais, permissões e limites de utilização habituais.

Que projetos se adequam e quais precisam de outro ambiente

Para os casos que precisam de um servidor ou de um processo Node permanente, utilize um ambiente que suporte e gira esse runtime, como uma plataforma de aplicações ou um VPS. Os workers de filas e consumidores escritos em PHP podem ficar em execução como processos persistentes nos planos Avanza, Max e Elastic, e o tempo real numa aplicação Laravel resolve-se com um serviço compatível com Pusher. Nem sempre precisa de acesso root: depende do serviço escolhido. O nome do framework não decide por si só a compatibilidade: o importante é se o build termina em ficheiros estáticos ou se a aplicação exige executar um servidor.

O caso do Next.js

O Next.js pode funcionar das duas formas e, por isso, costuma gerar dúvidas. Para produzir um site estático, configure a exportação, por exemplo em next.config.mjs:

const nextConfig = {
  output: 'export',
};

export default nextConfig;

Ao executar next build, o Next.js cria o diretório out, que contém os ficheiros que deve publicar. A documentação de exportações estáticas do Next.js detalha que funções este modo suporta.

Uma exportação estática não consegue resolver em cada visita lógica que dependa de um servidor Next.js, como SSR, cookies lidos no servidor, Server Actions ou rotas de API dinâmicas. Se o projeto utilizar essas funções, tem de as adaptar a uma API externa ou a endpoints PHP, ou alojar a aplicação num ambiente que suporte o seu runtime de servidor.

Publicar o projeto com o Deploy+

Pode publicar um frontend compilado com o Deploy+: cada implementação clona o repositório numa versão nova, executa aí o build e só a torna pública quando todos os comandos terminaram corretamente.

Ao ligar o repositório:

1. No passo Projeto, escolha Frontend compilado. O Deploy+ propõe dist como raiz web e um script que executa npm ci e npm run build.
2. Verifique o diretório que o seu projeto gera. Mantenha dist para a configuração habitual do Vite, mas mude-o para build, out ou outro caminho se a sua ferramenta utilizar um nome diferente. Uma exportação estática do Next.js utiliza out.
3. Reveja o script proposto. Cada linha é executada numa shell independente, pelo que todas as linhas que utilizem npm, npx ou node têm de ativar o NVM nessa mesma linha. O perfil já vem preparado desta forma.
4. Em Automatização, ative Implementar ao fazer push se quiser que cada alteração no ramo escolhido gere uma versão nova.

O Deploy+ verifica o Node.js antes de executar um script que precise dele e instala-o automaticamente se ainda não estiver disponível na conta. Se o seu package.json exigir uma versão concreta, selecione-a antes da primeira implementação em Alojamento → o seu serviço → Gestor de pacotes, como se explica no manual de instalação do Node.js e do npm.

Se npm ci indicar que o ficheiro de bloqueio falta ou não coincide, prepare-o em desenvolvimento, teste as dependências e guarde package-lock.json junto a package.json antes de implementar. Manter o ficheiro de bloqueio permite instalar as mesmas versões das dependências em cada build.

O script é executado antes de ativar a release. Se a instalação das dependências ou o build falharem, a versão anterior continua publicada e os visitantes não recebem um site compilado a meias. Se detetar um problema depois de a publicar, abra o histórico e utilize Voltar a esta versão numa release anterior. Quando essa release ainda está guardada, o Deploy+ só muda a ligação simbólica e o regresso demora segundos; se já tiver sido eliminada durante a limpeza de versões antigas, terá de a reconstruir a partir do repositório e demorará mais.

Voltar atrás altera o código e os assets publicados, mas não desfaz operações já realizadas na API externa nem restaura os dados ou a configuração do fornecedor.

O .env do Deploy+ e as chaves do serviço externo

O Deploy+ conserva o ficheiro .env na pasta partilhada e liga-o em cada release antes de executar o script. Num frontend estático, o empacotador lê as variáveis durante o build: não existe um processo Node.js que volte a ler o .env quando chega uma visita.

Qualquer valor incluído no JavaScript compilado pode ser visto por um visitante a partir do seu navegador. Mudar o nome da variável ou guardá-la num ficheiro .env não a torna secreta.

No bundle, inclua apenas valores públicos, por exemplo:

• O URL da API ou o identificador do projeto.
• Uma chave que o fornecedor descreva expressamente como pública, publicável ou destinada ao navegador.
• Identificadores públicos de análise ou de configuração.

Não inclua palavras-passe, chaves de administração, chaves secretas, chaves service_role, tokens privados nem credenciais de base de dados. Se uma operação precisar de um desses segredos, faça-a a partir do PHP e guarde a credencial no .env partilhado ou noutro ficheiro de configuração fora da raiz web. Carregue-a no PHP através do sistema de configuração do framework ou de uma biblioteca para .env, sem a enviar para o navegador nem a escrever em registos.

O Vite incorpora no bundle as variáveis com o prefixo VITE_, como avisa a sua documentação sobre variáveis de ambiente. O Next.js faz o mesmo com NEXT_PUBLIC_. Além disso, estes valores ficam fixados ao compilar: se alterar um, tem de voltar a executar o build e implementar o resultado.

Nem todos os fornecedores chamam o mesmo às suas credenciais nem oferecem uma chave adequada para o navegador. Consulte sempre a sua documentação. Por exemplo:

• O Supabase destina a chave publishable ao navegador e reserva a secret para o servidor. Os nomes antigos anon e service_role são os seus equivalentes herdados. A sua documentação de chaves indica que a chave pública deve ser acompanhada de Row Level Security e de permissões mínimas.
• A configuração web e as chaves do Firebase são públicas por design. O Firebase protege os dados através de Security Rules e App Check, e não ocultando essa configuração.

As chaves públicas não substituem os controlos de acesso. Ative no fornecedor as regras por utilizador, as políticas de linhas, as permissões de armazenamento, as restrições de utilização e as demais proteções que correspondam.

Rotas internas de uma SPA

Se a sua aplicação for uma SPA com um único index.html e gerir as rotas no navegador, um recarregamento direto de /panel pode devolver um erro 404. Nesse caso, adicione ao seu diretório público um ficheiro .htaccess que conserve os ficheiros reais e envie as restantes rotas para index.html:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.html [L]

Inclua o .htaccess no diretório que a ferramenta copia para o build; não basta deixá-lo numa pasta do repositório que não é publicada. A regra só se deve aplicar ao frontend: se partilhar a raiz com endpoints PHP ou rotas de API, exclua-os expressamente para não lhes devolver HTML.

Esta regra destina-se a SPA com encaminhamento do lado do cliente. Não a utilize sem mais numa exportação que já gera um ficheiro HTML diferente para cada rota.

Depois de publicar, abra o site a partir do seu domínio definitivo e teste o acesso direto a uma rota interna, o início de sessão, as chamadas à API e o envio de ficheiros, se existir.

O CORS não autentica utilizadores nem protege por si só a API face a outros clientes. Se adicionar um intermediário PHP, valide a sessão e as permissões e limite os destinos e as operações: não crie um proxy aberto que aceite qualquer URL do visitante. Configure também tempos de espera e reveja o resultado antes de repetir operações com efeitos.