Como hospedar aplicações Gatsby na Square Cloud

Hospedar um site Gatsby na Square Cloud exige que transformemos seu código de desenvolvimento em arquivos estáticos de produção e utilizemos um servidor para entregá-los. Diferente de um ambiente local, em produção focamos na pasta de saída final e na porta de rede obrigatória.

1. Realizando o Build de Produção

O Gatsby compila todo o seu conteúdo e componentes em uma pasta otimizada. Antes de realizar o deploy, execute o comando de build na sua máquina:

npx gatsby build

Este comando criará uma pasta chamada public/ na raiz do seu projeto. É importante notar que, diferente de outros frameworks que usam dist/, o Gatsby utiliza o diretório public/ para o resultado final.

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

A Square Cloud disponibiliza a porta 80 para sua aplicação utilizar e receber requisições. Utilizaremos o comando de inicialização para apontar o servidor para a pasta correta com a porta definida.

Comando de Start (Dashboard ou Config):

npx serve public -p 80

• Recomendado: runtime estático. Envie o conteúdo de public/ com um squarecloud⁠.app contendo MAIN=index.html (mantenha o index.html; o 404.html responde as rotas desconhecidas). Se usar o serve no Node, não use -s: o Gatsby gera um HTML por página e o -s esconde o 404.html. Instale com npm install serve e use RUNTIME=nodejs e START=npx serve public (a porta vem da variável PORT=80).
• public: Aponta para a pasta gerada pelo build.
• -p 80: Define a porta de escuta obrigatória da Square Cloud.

SSR

Este guia cobre sites Gatsby estáticos. Páginas com renderização no servidor (getServerData), Deferred Static Generation ou Gatsby Functions precisam de um servidor Gatsby e não são cobertas aqui.

3. O que deve conter no seu arquivo de deploy?

Ao criar o seu arquivo .zip para upload, inclua apenas o que é necessário para a execução:

• A pasta public/ completa.
• O arquivo package.json.

Atenção: Não envie a pasta node_modules, src ou .cache. Isso tornará o seu upload pesado e desnecessário, já que a Square Cloud cuida da instalação das dependências.

4. Dicas de Otimização e Cache

• Imagens: O Gatsby é excelente para otimizar imagens durante o build. Certifique-se de que o processo de build foi concluído com sucesso localmente para que todas as imagens processadas estejam na pasta public/.
• Variáveis de Ambiente: Se o seu build depende de APIs externas (como um CMS headless), lembre-se de configurar essas chaves no seu ambiente local antes de gerar o build, ou nos secrets do GitHub Actions, se o build for feito lá. As variáveis da Square Cloud valem só para a aplicação em execução.

Atualizado em: 04/10/2026