How to host Next.js applications

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:

{
  "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:

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:

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.

Updated on: 05/26/2026