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

# How to host a Next.js application

## 1. Prerequisites

* **Active Account and Plan:** Web server deployment requires an active account on the platform.
* **Node.js Environment:** Make sure your project is using a Node.js version compatible with Square Cloud.


## 2. Build Strategies

Unlike simple backend applications, Next.js needs to be compiled before running. You have two options on Square Cloud:

### Option A: Build on Square Cloud
To have Square Cloud run the build during deployment, you need to adjust your `package.json` file:
1. Move libraries from `devDependencies` to `dependencies` (especially `next`, `react`, and `react-dom` themselves).
2. Include `npm run build` in the startup command in addition to the start command. (e.g., `npm run build && npm run start`)

> **Tip:** Since this is a production environment, only 'dependencies' are installed, not 'devDependencies'. To install any package, list it strictly under 'dependencies'.

### Option B: Local Build
If you prefer to upload the project already compiled:
1. Run `npm run build` on your machine.
2. Make sure to include the hidden `.next` folder without the `cache` subfolder in your zip archive (`.zip`).


## 3. package.json Configuration

The most critical point for Next.js to work on Square Cloud is the port. The default `next start` command uses port 3000, but for production, use **port 80**.

Adjust your start script in `package.json`:

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



## 4. Performing the Deployment

1. **Compression:** Create a `.zip` file containing your source code, `package.json`, and (if you chose Option B) the `.next` folder. **Never include the `node_modules` folder**.
2. **Upload:** In the Square Cloud Dashboard, click on upload new application.
3. **Web Publishing:** In the submission menu, enable the **"Publish to Web"** option.
4. **Subdomain:** Define the name of your free subdomain (e.g., `my-site.squareweb.app`).
5. **Start Command:** The default command will be:
```bash
npm run start
```

## 5. Custom Domains (Standard plan or higher)

For professional projects, you can configure your own domain (e.g., `www.yourdomain.com`):
* Point your domain in the **Network** tab of the Dashboard.
* Square Cloud provides free and automatic **SSL (HTTPS)** for your domain, ensuring security and better SEO rankings.


## 6. Optimization Tips

* **Environment Variables:** Use the **ENV** tab in the Dashboard to define variables like `NEXT_PUBLIC_API_URL`. Remember that variables starting with `NEXT_PUBLIC_` are exposed to the client side.
* **Logs:** Use the Dashboard terminal to monitor the hydration process and potential SSR errors.

## 7. Bonus: CI/CD

We have a GitHub Action that simplifies updating your project with minimal downtime. This is an option where you do not need to build on Square; therefore, on Square, there will only be the 'start' command without the build. You can create a workflow like this to update your project with every released tag:

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

The Square Action used at the end automatically installs the CLI, logs in, and pushes the commit to the application.