Deploy di un sito Gatsby

Introduzione

Per sviluppare e ospitare un'applicazione Gatsby su Square Cloud, è essenziale seguire una sequenza strutturata di configurazioni e prerequisiti. Questa guida tecnica coprirà l’intero processo, dalla configurazione iniziale al deploy in produzione.

Prerequisiti

Account Square Cloud: Registrati tramite la pagina di registrazione usando la tua email.
Piano attivo: Garantisce risorse dedicate e prestazioni ottimizzate per la tua applicazione. Consulta i nostri piani disponibili e scegli quello più adatto alle tue esigenze.

Questa guida usa il runtime statico o il runtime Node.js. Testata con Gatsby 5 su Node.js 24 a settembre 2026.

Creare il progetto

Ti servono Node.js e npm sul tuo computer. Se non li hai, scaricali dal sito ufficiale di Node.js. Crea un progetto con l’inizializzatore ufficiale:

npm create gatsby@latest

L’inizializzatore chiede il nome del sito, la cartella e opzioni come TypeScript e un CMS, poi installa le dipendenze. Entra nella cartella che ha creato:

cd <your-site-folder>

Avvia il server di sviluppo con npm run develop (ascolta su http://localhost:8000). Le pagine si trovano in src/pages/: modifica src/pages/index.js (o index.tsx) per cambiare la home page.

Build per la produzione

npm run build

Gatsby scrive il sito nella cartella public/, un file HTML per pagina.

Scegliere come servirlo

Una build di Gatsby è un sito statico: file HTML, CSS e JavaScript che qualsiasi web server può distribuire. Scegli una di queste opzioni:

Runtime statico (consigliato)
Server Express
Pacchetto serve

Il runtime statico serve i file della tua build con un web server gestito da Square Cloud. Non gira nessun processo Node.js, quindi è il modo più leggero per ospitare un sito senza codice lato server.

Esegui la build del sito

Esegui npm run build. L’output finisce nella cartella public.

Mantieni funzionanti le route lato client

Se la tua app cambia pagina nel browser senza ricaricare (routing lato client), rinomina public/index.html in vite.html. Il runtime statico risponde con vite.html a ogni percorso che non corrisponde a un file, quindi ricaricare una route come /about carica comunque la tua app. Un sito con un file HTML per pagina mantiene index.html: i percorsi sconosciuti restituiscono allora il tuo 404.html. Consulta come il runtime statico serve i file.

Aggiungi il file di configurazione

Crea un file squarecloud.app dentro public. Un MAIN che punta a un file HTML seleziona il runtime statico:

squarecloud.app

MAIN=vite.html
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

Usa MAIN=index.html se hai mantenuto index.html. 512 MB è la memoria minima per un sito web. Quando carichi dalla dashboard, ti vengono chiesti questi valori e il file viene scritto per te.

Comprimi l'output della build

Comprimi il contenuto di public, non la cartella stessa, in modo che squarecloud.app si trovi nella radice dello ZIP. Con la CLI, esegui squarecloud upload dall’interno di public.

Tutto ciò che è nello ZIP è pubblico sul tuo sito. Carica solo l’output della build, mai il codice sorgente o i file .env.

La maggior parte degli strumenti di build svuota public a ogni build. Tieni una copia di squarecloud.app nella cartella che il tuo framework copia invariata nella build (public/ nei progetti basati su Vite), oppure ripeti gli ultimi tre passaggi dopo ogni build.

Questa opzione esegue un piccolo server Express sul runtime Node.js. Installa Express come dipendenza normale, non come devDependency, che Square Cloud non installa:

npm install express

Crea un file server.mjs nella radice del tuo progetto. Serve la cartella di output della build, public, e restituisce index.html per qualsiasi altro percorso, così il routing lato client continua a funzionare:

server.mjs

import express from 'express';
import path from 'node:path';

const app = express();
const distPath = path.join(import.meta.dirname, 'public');

app.use(express.static(distPath));

// SPA fallback: serve index.html for any route not matched above
app.use((req, res) => {
  res.sendFile(path.join(distPath, 'index.html'));
});

// Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container
const port = Number(process.env.PORT) || 80;
app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`));

Per provarlo sul tuo computer, scegli una porta libera: PORT=3000 node server.mjs.Crea un file squarecloud.app nella radice del tuo progetto. Square Cloud avvia il tuo sito con node server.mjs:

squarecloud.app

MAIN=server.mjs
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

Esegui npm run build prima di creare il tuo ZIP. Lo ZIP deve contenere server.mjs, package.json, squarecloud.app e la cartella public, senza node_modules: Square Cloud installa le tue dipendenze al primo avvio. Gli strumenti di build sono di solito devDependencies, che Square Cloud non installa, quindi la build va eseguita sul tuo computer.

Questa opzione esegue il pacchetto serve sul runtime Node.js, senza codice server da scrivere. Installalo come dipendenza normale:

npm install serve

Aggiungi uno script start:prod agli scripts del tuo package.json, accanto a quelli che hai già:

package.json

"scripts": {
  "start:prod": "serve -s public"
}

serve -s public serve la cartella di output della build, public, in modalità single-page: ogni percorso che non corrisponde a un file restituisce index.html, così il routing lato client continua a funzionare. serve ascolta su tutte le interfacce di rete, sulla porta indicata dalla variabile d’ambiente PORT, che Square Cloud imposta a 80 (in locale usa 3000).Crea un file squarecloud.app nella radice del tuo progetto:

squarecloud.app

RUNTIME=nodejs
START=npm run start:prod
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My website
SUBDOMAIN=mywebsite

RUNTIME=nodejs seleziona il runtime Node.js senza un file MAIN, e START sostituisce il comando di avvio predefinito.Esegui npm run build prima di creare il tuo ZIP. Lo ZIP deve contenere package.json, squarecloud.app e la cartella public, senza node_modules: Square Cloud installa le tue dipendenze al primo avvio. Gli strumenti di build sono di solito devDependencies, che Square Cloud non installa, quindi la build va eseguita sul tuo computer.

Gatsby scrive un file HTML per pagina, quindi sul runtime statico mantieni index.html (senza rinominarlo in vite.html): la tua pagina src/pages/404.js diventa il 404.html che risponde ai percorsi sconosciuti. Per conservare squarecloud.app tra una build e l’altra, mettilo nella cartella static/: Gatsby copia quella cartella invariata in public/.

Questa guida tratta i siti Gatsby statici. Le pagine che usano il rendering lato server (getServerData), la Deferred Static Generation o le Gatsby Functions richiedono un server Gatsby e non sono trattate qui.

Deploy e verifica

Crea lo ZIP descritto nell’opzione che hai scelto, poi caricalo:

Tramite dashboard

Accedi alla pagina di upload

Accedi alla pagina di upload e carica il file zip del tuo progetto.

Configura il tuo ambiente

Dopo aver caricato il tuo zip, dovrai configurare il nome, il file principale o il runtime environment e altre impostazioni per il tuo progetto.
Se stai caricando un progetto web, assicurati di selezionare “Web Publication” e di impostare un sottodominio per il tuo progetto.

Esegui il deploy del tuo progetto

Infine, clicca sul pulsante “Deploy” per ospitare il tuo progetto su Square Cloud.
Dopo il deploy, puoi monitorare lo stato e i log del tuo progetto dalla dashboard.

Caricamento dell'applicazione su Square Cloud

Conferma che la tua app sia online

Il primo deploy richiede di solito meno di un minuto. Nella dashboard, attendi che lo stato della tua applicazione mostri “in esecuzione” e controlla i log per eventuali errori di avvio.
Se hai fatto il deploy di un sito web o di un’API, apri https://<tuo-sottodominio>.squareweb.app nel tuo browser: dovresti vedere la tua applicazione rispondere. Se hai fatto il deploy di un bot, invia un comando per confermare che sia online.

La tua app non si avvia? Consulta la guida alla risoluzione dei problemi per le cause più comuni e le relative soluzioni.

Tramite CLI

Per utilizzare questo metodo, il tuo progetto deve avere un file di configurazione chiamato squarecloud.app nella sua radice. Indica a Square Cloud come eseguire la tua applicazione.

Guida al file di configurazione

Scopri come creare il file di configurazione squarecloud.app che definisce l’ambiente della tua applicazione.

Installa la CLI

Installa la CLI di Square Cloud. Se ce l’hai già, esegui lo stesso comando per aggiornarla:

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

Accedi

Esegui il comando qui sotto. Apre il tuo browser: approva l’accesso lì e la CLI è pronta. Non c’è nessuna chiave API da copiare. Per script e CI, consulta Autenticazione della CLI.

squarecloud auth login

Carica il tuo progetto

Dalla cartella del tuo progetto, esegui il comando qui sotto. La CLI comprime la cartella corrente, escludendo ciò che elenca squarecloud.ignore, e la carica:

squarecloud upload

Per caricare uno zip che hai creato tu, passalo con --file:

squarecloud upload --file <path/to/zip>

Conferma che la tua app sia online

Il primo deploy richiede di solito meno di un minuto. Controlla lo stato e i log della tua applicazione direttamente dal terminale:

squarecloud app status
squarecloud app logs

Se hai fatto il deploy di un sito web o di un’API, apri https://<tuo-sottodominio>.squareweb.app nel tuo browser: dovresti vedere la tua applicazione rispondere. Se hai fatto il deploy di un bot, invia un comando per confermare che sia online.

La tua app non si avvia? Consulta la guida alla risoluzione dei problemi per le cause più comuni e le relative soluzioni.

Errori comuni

Dominio personalizzato

Per utilizzare un dominio personalizzato (ad esempio, mysite.com) invece dell’URL predefinito mysite.squareweb.app, hai bisogno del piano Standard o superiore. L’URL predefinito deriva dal campo SUBDOMAIN nel file di configurazione. Per collegare il tuo dominio, segui come configurare il tuo dominio.

Requisiti minimi di RAM

Minimo: 512MB di RAM per siti web e API, sufficienti per una build statica sul runtime statico. Per le app che generano le pagine su un server (Next.js, Nuxt, Angular SSR e simili), consigliamo almeno 1GB di RAM. Per applicazioni più grandi, alloca più RAM per evitare che l’applicazione esaurisca la memoria e si arresti in modo anomalo.

Impossibile trovare questo sito.

Verifica che il sottodominio/dominio corrisponda a quanto configurato nel campo SUBDOMAIN o nelle impostazioni del dominio personalizzato. Se hai appena caricato il sito, attendi fino a 60 secondi affinché Square abiliti il primo accesso.

Il sito ha impiegato troppo tempo per rispondere…

Il tuo server deve ascoltare sulla porta 80 e sull’host 0.0.0.0. Square Cloud imposta le variabili d’ambiente PORT (80) e HOST (0.0.0.0) nella tua applicazione: leggile nel codice invece di scrivere altri valori fissi. Un server che ascolta solo su localhost o 127.0.0.1 non riceve mai richieste.

Prossimi passi

Variabili d'ambiente

Tieni segreti e impostazioni fuori dal codice e leggili in fase di esecuzione.

Dominio personalizzato

Pubblica la tua app sul tuo dominio, dal piano Standard in su.

Risoluzione dei problemi

Sistema un’app che non si avvia o un sito che non risponde.

Per saperne di più su Gatsby, consulta la documentazione ufficiale di Gatsby.

Contattaci

Se continui a riscontrare difficoltà tecniche, il nostro team di supporto specializzato è disponibile ad assisterti. Contattaci e saremo felici di aiutarti a risolvere qualsiasi problema: la qualità del supporto è una parte importante del motivo per cui gli sviluppatori valutano Square Cloud 4,9/5 su 402 recensioni su Google e Trustpilot.

Bots

Siti web

API e backend

Database

App self-hosted

Guide

Guide alla migrazione

Deploy di un sito Gatsby

Introduzione

Prerequisiti

Creare il progetto

Build per la produzione

Scegliere come servirlo

Deploy e verifica

Tramite dashboard

Tramite CLI

Guida al file di configurazione

Errori comuni

Dominio personalizzato

Requisiti minimi di RAM

Impossibile trovare questo sito.

Il sito ha impiegato troppo tempo per rispondere…

Prossimi passi

Variabili d'ambiente

Dominio personalizzato

Risoluzione dei problemi

Contattaci

​Introduzione

​Prerequisiti

​Creare il progetto

​Build per la produzione

​Scegliere come servirlo

​Deploy e verifica

​Tramite dashboard

​Tramite CLI

Guida al file di configurazione

​Errori comuni

​Dominio personalizzato

​Requisiti minimi di RAM

​Impossibile trovare questo sito.

​Il sito ha impiegato troppo tempo per rispondere…

​Prossimi passi

Variabili d'ambiente

Dominio personalizzato

Risoluzione dei problemi

​Contattaci

Introduzione

Prerequisiti

Creare il progetto

Build per la produzione

Scegliere come servirlo

Deploy e verifica

Tramite dashboard

Tramite CLI

Errori comuni

Dominio personalizzato

Requisiti minimi di RAM

Impossibile trovare questo sito.

Il sito ha impiegato troppo tempo per rispondere…

Prossimi passi

Contattaci