Como hospedar aplicações Astro na Square Cloud

Astro é conhecido por sua arquitetura de "ilhas" (islands) e por gerar sites extremamente rápidos. Na Square Cloud, você pode hospedar sites estáticos ou aplicações Astro com SSR (Server-Side Rendering). Recomendado: compacte o conteúdo de dist/ com um squarecloud⁠.app (MAIN=index.html, MEMORY=512) e use o runtime estático, sem processo Node. A alternativa abaixo usa a biblioteca serve no runtime Node.js.

1. O Processo de Build

Antes de enviar seus arquivos para a Square Cloud, você precisa gerar a versão de produção do seu site. O Astro compila seus componentes e conteúdos em arquivos HTML, CSS e JS otimizados.

No seu terminal local, execute:

npm run build

Este comando criará uma pasta chamada dist/ na raiz do seu projeto. É esta pasta que contém tudo o que seu usuário final verá.

2. Preparando o Servidor de Arquivos

Como o Astro (no modo estático) gera apenas arquivos, precisamos de um pequeno servidor para "servir" esses arquivos via HTTP. A biblioteca serve é a escolha recomendada por sua simplicidade.

No seu arquivo package.json, adicione a dependência:

"dependencies": {
  "serve": "^14.0.0"
}

3. Configurando a Porta e o Start

A Square Cloud disponibiliza a porta 80 para sua aplicação utilizar e receber requisições. O comando de inicialização deve ser configurado para apontar o servidor para a pasta de build e definir a porta correta.

Comando de Início (Start Command):

npx serve dist -p 80

• dist: Indica a pasta onde estão os arquivos compilados.
• -p 80: Define a porta obrigatória para o tráfego na Square Cloud.

4. Estrutura do Arquivo de Deploy (.zip)

Para realizar o upload, crie um arquivo comprimido contendo apenas o essencial para a execução:

• A pasta dist/ (Gerada pelo build).
• O arquivo package.json.
• O squarecloud⁠.app, por exemplo: RUNTIME=nodejs, START=npm run start:prod (com o script "start:prod": "serve -s dist"), MEMORY=512, SUBDOMAIN=.... A Square não instala devDependencies, então deixe o serve em dependencies.

Dica: Não inclua a pasta node_modules ou a pasta src. A Square Cloud instalará as dependências necessárias automaticamente.

5. Astro com SSR (Opcional)

Se você estiver usando o Astro com um adaptador (como Node.js) para renderização no lado do servidor (SSR), o processo muda levemente:

1. O comando de build ainda é necessário.
2. Adicione o adaptador com npx astro add node (modo standalone), rode npm run build e use MAIN=dist/server/entry.mjs no squarecloud⁠.app. A Square define PORT=80 e HOST=0.0.0.0.

Atualizado em: 04/10/2026