Como hospedar aplicações Preact na Square Cloud

O Preact entrega o máximo de performance com o mínimo de tamanho. Para colocar seu projeto Preact no ar na Square Cloud (seja ele criado com o ecossistema do Vite ou via Preact CLI), nós compilamos a aplicação em arquivos estáticos e os servimos usando a biblioteca serve na porta padrão da plataforma.

1. Gerando o Build de Produção

Antes de enviar seu projeto para a nuvem, você deve transformá-lo em arquivos otimizados e minificados prontos para o navegador.

No terminal do seu projeto local, execute o comando de compilação:

npm run build

• Se você usa Vite (Padrão atual): O comando gerará a pasta dist/ na raiz do seu projeto.
• Se você usa o Preact CLI clássico: O comando gerará a pasta build/.

Para este guia, assumiremos o uso da pasta dist/ padrão do Vite.

2. Configurando o Comando de Início e a Porta 80

A Square Cloud utiliza a porta 80 para direcionar o tráfego. Você deve configurar seu comando de inicialização (no Dashboard ou no seu arquivo squarecloud.app) para abrir o servidor web apontando para a pasta correta.

Comando de Start:

npx serve -s dist -p 80

• -s (Single Page Application): Esse parâmetro é crucial. Ele garante que, se você usar o preact-router ou qualquer outro sistema de rotas, todas as requisições internas (como /dashboard ou /perfil) sejam redirecionadas para o index.html, evitando o temido erro 404 ao atualizar a página.
• dist: Indica a pasta que contém o resultado do seu build.
• -p 80: Define a porta de rede da Square Cloud.

3. Estrutura do Arquivo de Envio (.zip)

Para realizar o upload, crie um arquivo compactado .zip contendo apenas o ecossistema necessário para a execução.

• O que INCLUIR: A pasta dist/ (ou build/), o arquivo package.json e o package-lock.json (ou yarn.lock).
• O que EXCLUIR: A pasta node_modules/ e a pasta src/. A Square Cloud se encarregará de baixar e instalar todas as dependências de forma limpa diretamente no servidor.

4. Dicas de Otimização

• Variáveis de Ambiente: Se o seu frontend Preact consome uma API externa, certifique-se de configurar as URLs nas variáveis de ambiente. Se estiver usando o Vite, lembre-se de que as variáveis que precisam ser expostas ao navegador devem começar com o prefixo VITE_ (ex: VITE_API_URL).
• Aliasing do React: Se você está usando bibliotecas do ecossistema do React tradicional no seu projeto Preact (via preact/compat), certifique-se de que o alias está configurado corretamente no seu arquivo vite.config.js antes de rodar o comando de build para o deploy.

Atualizado em: 25/05/2026