Faça deploy de uma aplicação Preact

Introdução

Para desenvolver e hospedar uma aplicação Preact na Square Cloud, siga a sequência de configurações e pré-requisitos abaixo. Este guia cobre todo o processo, da configuração inicial ao deploy em produção.

Pré-requisitos

Conta Square Cloud: Cadastre-se através da página de cadastro usando seu e-mail.
Plano ativo: Garante recursos dedicados e desempenho otimizado para seu aplicativo. Confira nossos planos disponíveis e escolha o mais adequado às suas necessidades.

Este guia usa o runtime estático ou o runtime Node.js. Testado com Preact 10 e Vite 8 no Node.js 24 em setembro de 2026.

Crie o projeto

Você precisa do Node.js e do npm na sua máquina. Se ainda não os tiver, baixe-os no site oficial do Node.js. Crie um projeto com o inicializador oficial, o create-preact:

npm init preact

O inicializador pergunta a pasta do projeto e opções como TypeScript, o router e a pré-renderização (SSG). Você não precisa instalar o antigo preact-cli. Depois, entre na pasta do projeto e instale as dependências, se o inicializador não tiver feito isso:

cd <your-project-name>
npm install

Inicie o servidor de desenvolvimento com npm run dev e edite o src/index.jsx (ou src/index.tsx) para mudar a página inicial.

Faça o build para produção

npm run build

Os projetos create-preact fazem o build com o Vite, que grava os arquivos de produção na pasta dist/.

Escolha como servir o site

Um build do Preact é um site estático: arquivos HTML, CSS e JavaScript que qualquer servidor web consegue entregar. Escolha uma destas opções:

Runtime estático (recomendado)
Servidor Express
Pacote serve

O runtime estático serve os arquivos do seu build com um servidor web gerenciado pela Square Cloud. Nenhum processo Node.js roda, então essa é a forma mais leve de hospedar um site sem código no servidor.

Faça o build do site

Execute npm run build. A saída vai para a pasta dist.

Mantenha as rotas do lado do cliente funcionando

Se a sua aplicação troca de página no navegador sem recarregar (roteamento no lado do cliente), renomeie dist/index.html para vite.html. O runtime estático responde qualquer caminho que não seja um arquivo com o vite.html, então recarregar uma rota como /about continua carregando a sua aplicação. Um site com um arquivo HTML por página mantém o index.html: caminhos desconhecidos passam a retornar o seu 404.html. Veja como o runtime estático serve os arquivos.

Adicione o arquivo de configuração

Crie um arquivo squarecloud.app dentro de dist. Um MAIN que aponta para um arquivo HTML seleciona o runtime estático:

squarecloud.app

MAIN=vite.html
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

Use MAIN=index.html se você manteve o index.html. 512 MB é a memória mínima para um site. Quando você faz o upload pelo dashboard, ele pede esses valores e escreve o arquivo para você.

Compacte a saída do build

Compacte o conteúdo de dist, e não a pasta em si, para que o squarecloud.app fique na raiz do ZIP. Com a CLI, execute squarecloud upload de dentro de dist.

Tudo o que está no ZIP fica público no seu site. Envie apenas a saída do build, nunca o código-fonte ou arquivos .env.

A maioria das ferramentas de build esvazia dist a cada build. Mantenha uma cópia do squarecloud.app na pasta que o seu framework copia sem alterações para o build (public/ em projetos baseados em Vite), ou repita os três últimos passos após cada build.

Esta opção roda um pequeno servidor Express no runtime Node.js. Instale o Express como dependência comum, e não como devDependency, que a Square Cloud não instala:

npm install express

Crie um arquivo server.mjs na raiz do projeto. Ele serve a pasta de saída do build, dist, e retorna o index.html para qualquer outro caminho, para que o roteamento no lado do cliente continue funcionando:

server.mjs

import express from 'express';
import path from 'node:path';

const app = express();
const distPath = path.join(import.meta.dirname, 'dist');

app.use(express.static(distPath));

// Fallback SPA: serve o index.html para qualquer rota não atendida acima
app.use((req, res) => {
  res.sendFile(path.join(distPath, 'index.html'));
});

// A Square Cloud define PORT=80; 0.0.0.0 aceita conexões de fora do container
const port = Number(process.env.PORT) || 80;
app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`));

Para testar na sua máquina, escolha uma porta livre: PORT=3000 node server.mjs.Crie um arquivo squarecloud.app na raiz do projeto. A Square Cloud inicia o seu site com node server.mjs:

squarecloud.app

MAIN=server.mjs
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

Execute npm run build antes de criar o ZIP. O ZIP precisa conter server.mjs, package.json, squarecloud.app e a pasta dist, sem node_modules: a Square Cloud instala as dependências na primeira inicialização. As ferramentas de build costumam ser devDependencies, que a Square Cloud não instala, então o build precisa rodar na sua máquina.

Esta opção roda o pacote serve no runtime Node.js, sem nenhum código de servidor para escrever. Instale-o como dependência comum:

npm install serve

Adicione um script start:prod aos scripts do seu package.json, ao lado dos que você já tem:

package.json

"scripts": {
  "start:prod": "serve -s dist"
}

serve -s dist serve a pasta de saída do build, dist, no modo single-page: qualquer caminho que não seja um arquivo retorna o index.html, para que o roteamento no lado do cliente continue funcionando. O serve escuta em todas as interfaces de rede, na porta da variável de ambiente PORT, que a Square Cloud define como 80 (localmente, ele usa 3000).Crie um arquivo squarecloud.app na raiz do projeto:

squarecloud.app

RUNTIME=nodejs
START=npm run start:prod
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

RUNTIME=nodejs seleciona o runtime Node.js sem um arquivo MAIN, e START substitui o comando de inicialização padrão.Execute npm run build antes de criar o ZIP. O ZIP precisa conter package.json, squarecloud.app e a pasta dist, sem node_modules: a Square Cloud instala as dependências na primeira inicialização. As ferramentas de build costumam ser devDependencies, que a Square Cloud não instala, então o build precisa rodar na sua máquina.

Faça o deploy e verifique

Crie o ZIP descrito na opção que você escolheu e faça o upload:

Via dashboard

Acesse a página de upload

Acesse a página de upload e envie seu arquivo zip.

Configure seu ambiente

Após fazer o upload do seu arquivo zip, você precisará configurar o nome, o arquivo principal ou o ambiente de execução e outras configurações do seu projeto.
Se você estiver enviando um projeto web, certifique-se de selecionar “Publicação na Web” e definir um subdomínio para o seu projeto.

Faça o deploy do projeto

Por fim, clique no botão “Deploy” para hospedar seu projeto na Square Cloud. Após o deploy, você poderá monitorar o status e os registros do seu projeto no dashboard.

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. No dashboard, aguarde o status da sua aplicação mudar para em execução e verifique os registros em busca de erros de inicialização.
Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.

Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Via CLI

Para usar esse método, seu projeto precisa de um arquivo de configuração chamado squarecloud.app na raiz. Ele informa à Square Cloud como executar a sua aplicação.

Guia do arquivo de configuração

Saiba como criar o arquivo de configuração squarecloud.app que define o ambiente da sua aplicação.

Instale a CLI

Instale a CLI da Square Cloud. Se você já a tem, execute o mesmo comando para atualizá-la:

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

Faça login

Execute o comando abaixo. Ele abre o seu navegador: aprove o login lá e a CLI está pronta. Não há nenhuma chave de API para copiar. Para scripts e CI, veja autenticação da CLI.

squarecloud auth login

Envie o seu projeto

Na pasta do seu projeto, execute o comando abaixo. A CLI compacta a pasta atual, deixando de fora o que o squarecloud.ignore lista, e faz o upload:

squarecloud upload

Para enviar um zip que você mesmo criou, passe-o com --file:

squarecloud upload --file <caminho/para/zip>

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. Verifique o status e os registros da sua aplicação diretamente pelo terminal:

squarecloud app status
squarecloud app logs

Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.

Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Erros comuns

Domínio personalizado

Para usar um domínio personalizado (ex.: meusite.com) no lugar da URL padrão meusite.squareweb.app, você precisa do plano Standard ou superior. A URL padrão vem do campo SUBDOMAIN no arquivo de configuração. Para conectar o seu domínio, veja como configurar seu próprio domínio.

Requisitos mínimos de RAM

Mínimo: 512MB de RAM para sites e APIs, o suficiente para um build estático no runtime estático. Para aplicações que renderizam páginas no servidor (Next.js, Nuxt, Angular SSR e similares), recomendamos pelo menos 1GB de RAM. Para aplicações maiores, aloque mais RAM para evitar que a aplicação fique sem memória e trave.

Não foi possível encontrar esse site.

Verifique se o subdomínio/domínio corresponde ao configurado no campo SUBDOMAIN ou nas configurações de domínio personalizado. Se você acabou de enviar o site, aguarde até 60 segundos para a Square liberar o primeiro acesso.

Site demorou demais para responder…

O seu servidor precisa escutar na porta 80 e no host 0.0.0.0. A Square Cloud define as variáveis de ambiente PORT (80) e HOST (0.0.0.0) na sua aplicação: leia essas variáveis no código em vez de fixar outros valores. Um servidor que escuta apenas em localhost ou 127.0.0.1 nunca recebe requisições.

Recarregar uma rota retorna 404

A sua aplicação usa o router do Preact e o servidor não conhece a rota. No runtime estático, renomeie o index.html para vite.html. As opções Express e serve acima já retornam o index.html para caminhos desconhecidos.

Próximos passos

Variáveis de ambiente

Mantenha segredos e configurações fora do código e leia-os em tempo de execução.

Domínio personalizado

Sirva a sua aplicação no seu próprio domínio, a partir do plano Standard.

Solução de problemas

Corrija uma aplicação que não inicia ou um site que não responde.

Para saber mais sobre o Preact, consulte a documentação oficial do Preact.

Contate-nos

Se você continuar enfrentando dificuldades técnicas, nossa equipe de suporte especializada está disponível para auxiliá-lo. Entre em contato conosco e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com 4,9/5 em 402 avaliações no Google e Trustpilot.

Bots

Sites

APIs e backends

Bancos de dados

Aplicações self-hosted

Guias

Guias de migração

Faça deploy de uma aplicação Preact

Introdução

Pré-requisitos

Crie o projeto

Faça o build para produção

Escolha como servir o site

Faça o deploy e verifique

Via dashboard

Via CLI

Guia do arquivo de configuração

Erros comuns

Domínio personalizado

Requisitos mínimos de RAM

Não foi possível encontrar esse site.

Site demorou demais para responder…

Recarregar uma rota retorna 404

Próximos passos

Variáveis de ambiente

Domínio personalizado

Solução de problemas

Contate-nos

​Introdução

​Pré-requisitos

​Crie o projeto

​Faça o build para produção

​Escolha como servir o site

​Faça o deploy e verifique

​Via dashboard

​Via CLI

Guia do arquivo de configuração

​Erros comuns

​Domínio personalizado

​Requisitos mínimos de RAM

​Não foi possível encontrar esse site.

​Site demorou demais para responder…

​Recarregar uma rota retorna 404

​Próximos passos

Variáveis de ambiente

Domínio personalizado

Solução de problemas

​Contate-nos

Introdução

Pré-requisitos

Crie o projeto

Faça o build para produção

Escolha como servir o site

Faça o deploy e verifique

Via dashboard

Via CLI

Erros comuns

Domínio personalizado

Requisitos mínimos de RAM

Não foi possível encontrar esse site.

Site demorou demais para responder…

Recarregar uma rota retorna 404

Próximos passos

Contate-nos