Cómo alojar aplicaciones Gatsby en Square Cloud

Alojar un sitio Gatsby en Square Cloud exige que transformemos tu código de desarrollo en archivos estáticos de producción y utilicemos un servidor para entregarlos. A diferencia de un entorno local, en producción nos enfocamos en la carpeta de salida final y en el puerto de red obligatorio.

1. Realizando el build de producción

Gatsby compila todo tu contenido y componentes en una carpeta optimizada. Antes de realizar el deploy, ejecuta el comando de build en tu máquina:

npx gatsby build

Este comando creará una carpeta llamada public/ en la raíz de tu proyecto. Es importante notar que, a diferencia de otros frameworks que usan dist/, Gatsby utiliza el directorio public/ para el resultado final.

2. Configurando el puerto y el comando de inicio

Square Cloud pone a disposición el puerto 80 para que tu aplicación lo utilice y reciba peticiones. Utilizaremos el comando de inicio para apuntar el servidor a la carpeta correcta con el puerto definido.

• Recomendado: runtime estático. Envía el contenido de public/ con un squarecloud⁠.app que contenga MAIN=index.html (mantén el index.html; el 404.html responde a las rutas desconocidas).
• Alternativa con Node.js: instala serve con npm install serve y usa RUNTIME=nodejs y el comando de inicio a continuación. No uses -s: Gatsby genera un HTML por página y el -s oculta el 404.html.

npx serve public -p 80

SSR

Esta guía cubre sitios Gatsby estáticos. Las páginas con renderizado en el servidor (getServerData), Deferred Static Generation y Gatsby Functions necesitan un servidor de Gatsby y no están cubiertas aquí.

3. ¿Qué debe contener tu archivo de deploy?

Al crear tu archivo .zip para el upload, incluye solo lo necesario para la ejecución:

• La carpeta public/ completa.
• El archivo package.json.

Atención: No envíes la carpeta node_modules, src ni .cache. Eso haría tu upload pesado e innecesario, ya que Square Cloud se encarga de la instalación de las dependencias.

4. Consejos de optimización y caché

• Imágenes: Gatsby es excelente para optimizar imágenes durante el build (redimensiona y genera formatos modernos). Asegúrate de que el build se haya completado con éxito localmente antes de comprimir.
• Variables de entorno: Gatsby inserta las variables en el build. Deben existir donde se ejecuta el build (tu máquina o GitHub Actions); las variables del dashboard de Square Cloud no llegan a un sitio ya compilado.

Actualizado el: 04/10/2026