Cómo alojar aplicaciones Next.js en Square Cloud

1. Requisitos previos

• Cuenta y Plan Activo: El deploy de webservers exige una cuenta activa en la plataforma.
• Entorno Node.js: Asegúrate de que tu proyecto utiliza una versión de Node.js compatible con Square Cloud.

2. Estrategias de build (compilación)

A diferencia de las aplicaciones simples de backend, Next.js necesita compilarse antes de ejecutarse. Tienes dos opciones en Square Cloud:

Opción A: Build en Square Cloud

Para que Square Cloud realice el build durante el deploy, debes ajustar tu archivo package.json:

1. Mueve las bibliotecas de devDependencies a dependencies (especialmente el propio next, react y react-dom).
2. Pasa en el comando de inicio el npm run build además del comando de iniciar. (Ej.: npm run build && npm run start)

Consejo: Por ser un entorno de producción, solo se instalan las 'dependencies', sin 'devDependencies'. Para instalar cualquier paquete, decláralo solo en 'dependencies'.

Opción B: Build local

Si prefieres enviar el proyecto ya compilado:

1. Ejecuta npm run build en tu máquina.
2. Asegúrate de incluir la carpeta oculta .next sin la subcarpeta cache en tu archivo comprimido (.zip).

3. Configuración del package.json

El punto más crítico para el funcionamiento de Next.js en Square Cloud es el puerto. El comando next start por defecto utiliza el puerto 3000, pero para producción usa el puerto 80.

Ajusta tu script de inicio en el package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start -p 80"
  }
}

4. Realizando el deploy

1. Compresión: Crea un archivo .zip que contenga tu código fuente, el package.json y (si elegiste la Opción B) la carpeta .next. Nunca incluyas la carpeta node_modules.
2. Upload: En el Dashboard de Square Cloud, haz clic en enviar nueva aplicación.
3. Publicación Web: En el menú de envío, activa la opción "Publicar en la Web".
4. Subdominio: Define el nombre de tu subdominio gratuito (ej.: mi-sitio.squareweb.app).
5. Comando de inicio: El comando por defecto será:

    npm run start

5. Dominios personalizados (plan Standard o superior)

Para proyectos profesionales, puedes configurar tu propio dominio (ej.: www.tusitio.com):

• Realiza el apuntamiento en la pestaña Network del Dashboard.
• Square Cloud proporciona SSL (HTTPS) automático y gratuito para tu dominio, garantizando seguridad y mejores rankings en el SEO.

6. Consejos de optimización

• Variables de entorno: Utiliza la pestaña ENV en el Dashboard para definir variables como NEXT_PUBLIC_API_URL. Recuerda que las variables que empiezan con NEXT_PUBLIC_ se exponen en el lado del cliente.
• Logs: Utiliza la terminal del Dashboard para seguir el proceso de hidratación y posibles errores de SSR.

7. Extra: CI/CD

Tenemos una GitHub Action que facilita la actualización de tu proyecto con el menor downtime posible. Esta es una opción donde no necesitas hacer el build en Square Cloud, por lo tanto, en Square solo habrá el comando de 'start' sin el build. Puedes crear un workflow como este para actualizar tu proyecto con cada tag lanzada:

name: "Deploy Nextjs app"
on:
  push:
    tags:
      - "v*"
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Install dependencies
        run: npm install

      - name: Build website
        run: npm run build && chmod -R 777 .next next.config.ts package.json

      - name: Add website to zip
        run: zip -r project.zip package.json .next next.config.ts public -x ".next/cache/*"

      - name: Deploy on Square Cloud
        uses: squarecloudofc/github-action@v2
        with:
          command: commit --file project.zip ${{ secrets.SQUARECLOUD_APP_ID }} --restart
          token: '${{ secrets.SQUARE_CLOUD_TOKEN }}'

La Action de Square, usada al final, ya instala la CLI, hace el login y envía el commit a la aplicación.

Actualizado el: 13/06/2026