> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Cómo alojar una aplicación Next.js

## 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`:

```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á:
```bash
    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:

```yaml
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.