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:

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):

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.

Updated on: 05/26/2026