> ## 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 Gatsby site

# How to Host Gatsby Applications on Square Cloud

Hosting a Gatsby site on Square Cloud requires transforming your development code into static production files and using a server to deliver them. Unlike a local environment, in production, we focus on the final output folder and the mandatory network port.

---

## 1. Running the Production Build

Gatsby compiles all your content and components into an optimized folder. Before deploying, run the build command on your machine:

```bash
npx gatsby build
```

This command will create a folder named **`public/`** at the root of your project. It is important to note that, unlike other frameworks that use `dist/`, Gatsby uses the `public/` directory for the final output.

---

## 2. Configuring the Port and Start Command

Square Cloud makes **port 80** available for your application to use and receive requests. We will use the initialization command to point the server to the correct folder with the defined port.

### Start Command (Dashboard or Config):
```bash
npx serve -s public -p 80
```

* **`-s` (Single Page Application):** Essential for Gatsby routing to work properly, avoiding 404 errors when refreshing the page on internal routes.
* **`public`:** Points to the folder generated by the build.
* **`-p 80`:** Sets the mandatory listening port for Square Cloud.

### SSR (Server-Side Rendering)
For SSR builds that emit a server bundle, simply configure the main file to `server.js`.

---

## 3. What Should Your Deployment File Contain?

When creating your **.zip** file for upload, include only what is necessary for execution:

* The complete **`public/`** folder.
* The **`package.json`** file.

> **Attention:** Do not send the `node_modules`, `src`, or `.cache` folders. This will make your upload heavy and unnecessary, since Square Cloud takes care of installing dependencies.

---

## 4. Optimization and Caching Tips

* **Images:** Gatsby is excellent at optimizing images during the build. Make sure the build process completed successfully locally so that all processed images are in the `public/` folder.
* **Environment Variables:** If your build depends on external APIs (like a headless CMS), remember to configure these keys in your local environment before generating the build, or use Square Cloud's **Variables** system if your build is done via GitHub Actions.