> ## 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).

# Como hospedar uma aplicação Next.js

## 1. Pré-requisitos

* **Conta e Plano Ativo:** O deploy de webservers exige uma conta ativa na plataforma.
* **Ambiente Node.js:** Certifique-se de que seu projeto está utilizando uma versão do Node.js compatível com a Square Cloud.


## 2. Estratégias de build (compilação)

Diferente de aplicações simples de backend, o Next.js precisa ser compilado antes de rodar. Você tem duas opções na Square Cloud:

### Opção A: Build na Square Cloud
Para que a Square Cloud realize o build durante o deploy, você precisa ajustar seu arquivo `package.json`:
1.  Mova as bibliotecas de `devDependencies` para `dependencies` (especialmente o próprio `next`, `react` e `react-dom`).
2. Passe no comando de inicialização o `npm run build` além do comando de iniciar. (Ex.: `npm run build && npm run start`)

> **Dica:** Por ser ambiente de produção, é instalado apenas 'dependências', sem 'devdependencies'. Para instalar qualquer pacote, informe ele apenas em 'dependencies'

### Opção B: build local
Se você preferir enviar o projeto já compilado:
1.  Rode `npm run build` na sua máquina.
2.  Certifique-se de incluir a pasta oculta `.next` sem a subpasta `cache` no seu arquivo de compactação (.zip).


## 3. Configuração do package.json

O ponto mais crítico para o funcionamento do Next.js na Square Cloud é a porta. O comando `next start` padrão utiliza a porta 3000, mas para produção use a **porta 80**.

Ajuste seu script de início no `package.json`:

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



## 4. Realizando o deploy

1.  **Compactação:** Crie um arquivo `.zip` contendo seu código fonte, o `package.json` e (se optou pela Opção B) a pasta `.next`. **Nunca inclua a pasta `node_modules`**.
2.  **Upload:** No Dashboard da Square Cloud, clique em enviar nova aplicação.
3.  **Publicação Web:** No menu de envio, ative a opção **"Publicar na Web"**.
4.  **Subdomínio:** Defina o nome do seu subdomínio gratuito (ex: `meu-site.squareweb.app`).
5.  **Comando de Início:** O comando padrão será:
```bash
    npm run start
```

## 5. Domínios personalizados (plano Standard ou superior)

Para projetos profissionais, você pode configurar seu próprio domínio (ex: `www.seusite.com.br`):
* Realize o apontamento na aba **Network** do Dashboard.
* A Square Cloud fornece **SSL (HTTPS)** automático e gratuito para o seu domínio, garantindo segurança e melhores rankings no SEO.


## 6. Dicas de otimização

* **Variáveis de Ambiente:** Utilize a aba **ENV** no Dashboard para definir variáveis como `NEXT_PUBLIC_API_URL`. Lembre-se que variáveis que começam com `NEXT_PUBLIC_` são expostas no lado do cliente.
* **Logs:** Utilize o terminal do Dashboard para acompanhar o processo de hidratação e possíveis erros de SSR.

## 7. Extra: CI/CD

Temos uma GitHub Action que facilita a atualização do seu projeto com menor downtime possível. Esta é uma opção onde você não precisa buildar na Square, portanto, na Square haverá apenas o comando de 'start' sem o build. Você pode criar um workflow como este para atualizar seu projeto a cada tag lançada:

```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 }}'
```

A Action da Square, usada no final, já instala a CLI, faz o login e envia o commit para a aplicação.