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 -s public -p 80

• -s (Single Page Application): Essencial para que o roteamento do Gatsby funcione corretamente, evitando erros 404 ao atualizar a página em rotas internas.
• public: Aponta para a pasta gerada pelo build.
• -p 80: Define a porta de escuta obrigatória da Square Cloud.

SSR

Para builds SSR que emitem um bundle de servidor, basta configurar o arquivo principal para server.js.

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 utilize o sistema de Variáveis da Square Cloud se o seu build for feito via GitHub Actions.

Atualizado em: 14/05/2026