Quando un progetto funziona in locale, prima o poi arriva una domanda molto semplice: come lo pubblico davvero online?

Questa guida parte da qui. L’idea è rendere più chiaro il passaggio tra progetto locale e versione pubblicata, senza complicarlo inutilmente e senza farlo sembrare più misterioso di quanto sia.

Non è una guida pensata per coprire ogni caso possibile. È una base pratica per capire cosa significa deploy, quali passaggi contano davvero all’inizio e quali errori conviene evitare nei primi tentativi.

Deploy significa portare un progetto dal tuo computer a un ambiente accessibile online.

Detto in modo più pratico: smetti di avere un sito o un’app che funziona solo in locale e inizi ad avere un URL che puoi aprire da browser e condividere con altre persone.

In mezzo però c’è quasi sempre un passaggio tecnico importante:

• in locale lavori su file sorgente;
• online spesso pubblichi una build pronta per essere servita;
• l’hosting prende quei file e li espone sul web.

Capire questo ti evita uno degli equivoci più comuni: pensare che deploy significhi solo “caricare una cartella”. A volte è così, ma spesso prima devi generare l’output giusto.

Prima del deploy, conviene fare un controllo molto semplice ma serio. Il progetto dovrebbe essere già stabile in locale.

• la build deve completarsi senza errori;
• le pagine principali devono aprirsi correttamente;
• asset, immagini e font devono avere path coerenti;
• non dovresti avere segreti dentro al repository;
• la base Git dovrebbe essere pulita e comprensibile.

Se qualcosa è fragile in locale, online tende a peggiorare, non a migliorare.

Se stai ancora sistemando il workflow quotidiano di progetto, la guida VSCode essenziale aiuta molto a tenere ordinati terminale, task e debug, mentre GitHub operativo ti torna utile per la parte di repository e pubblicazione del codice.

Qui conviene fare una distinzione importante: non tutti i deploy funzionano allo stesso modo.

Nel caso più semplice puoi avere file già pronti, magari HTML, CSS e JavaScript, e caricarli manualmente sul server o nel pannello dell’hosting. In scenari del genere può anche esistere una cartella separata con file già minificati o preparati a mano, senza una pipeline automatica vera e propria.

Su molti progetti moderni invece non pubblichi direttamente i file sorgente. Pubblici il risultato della build.

Nei progetti che usano tool come Vite, Webpack, Parcel o altri builder, la pubblicazione non è solo una compressione finale fatta all’ultimo momento. Il progetto nasce già con una struttura pensata per passare attraverso una build.

Questo significa che il progetto ha già una certa organizzazione di partenza: file sorgente, dipendenze, script, configurazioni, cartelle di lavoro e un comando che sa come trasformare tutto in una versione finale pronta per il deploy.

In pratica il working tree contiene spesso materiale che online non deve andare così com’è:

• file sorgente pensati per essere trasformati;
• dipendenze e tooling di sviluppo;
• configurazioni del builder;
• asset che verranno ottimizzati o riscritti durante la build.

La build è il processo che prepara il progetto per la distribuzione: ottimizza gli asset, minifica il codice, risolve le dipendenze e genera i file finali dentro una cartella di output come dist, build o simili.

Questo approccio ha un costo iniziale in più, perché il progetto è più strutturato, ma porta vantaggi molto concreti: automazione, meno passaggi manuali, output più coerente, minori errori ripetitivi e un deploy più facile da rifare ogni volta nello stesso modo.

Per questo, prima di parlare di comandi o hosting, conviene capire che tipo di progetto hai davanti e quale strada ha più senso seguire per pubblicarlo, ad esempio:

• un sito molto semplice, in cui i file da mettere online sono già pronti e puoi caricarli direttamente;
• un lavoro in cui prepari prima una versione finale separata, come una cartella con file minificati o sistemati a mano, e pubblichi quella;
• una base moderna costruita per usare un builder come Vite, che genera automaticamente i file finali a partire dai sorgenti.

Se prendiamo uno scenario oggi molto diffuso nel front-end moderno, il quadro è questo: repository Git, builder locale come Vite e hosting collegato al repository, così il deploy può diventare quasi una conseguenza naturale del push.

Non è l’unico modello possibile, ma per siti statici e molte applicazioni front-end è diventato uno standard di fatto perché tiene insieme automazione, ottimizzazione e ripetibilità.

In questo tipo di setup, il punto centrale non è ricordarsi tanti comandi a memoria. Il punto centrale è sapere quale passaggio genera davvero la versione finale del progetto e quale cartella contiene i file che devono andare online.

Di solito questa versione finale viene prodotta dalla build e finisce in una cartella come dist, build o simili, in base a come il progetto è configurato.

Questa distinzione serve perché, quando colleghi il repository a un hosting automatico, la piattaforma deve sapere con precisione tre cose:

• quale repository o cartella devono leggere;
• quale comando devono eseguire per fare la build;
• quale cartella finale devono pubblicare.

Quando questi dati sono impostati bene, il vantaggio è molto concreto: fai push, la piattaforma ricostruisce il progetto e pubblica l’output corretto senza dover ripetere ogni volta lo stesso lavoro a mano.

Se invece stai caricando i file manualmente, il principio non cambia: devi comunque capire quali file sono i sorgenti e quali sono quelli finali da pubblicare. Se questa distinzione resta confusa, il deploy si rompe o si configura male molto facilmente.

Qui la cosa importante da capire non è tanto l’etichetta, ma il meccanismo pratico.

In questo caso tu arrivi ad avere una serie di file finali già pronti, per esempio le pagine del sito, i CSS, gli script, le immagini e i font.

A quel punto la piattaforma prende quei file e li pubblica online così come sono, senza chiederti di gestire da solo una macchina, un server complesso o configurazioni più pesanti.

Per chi inizia, questa è spesso la strada più semplice e sensata. Va benissimo per siti HTML/CSS/JS, landing page, portfolio, documentazione e molti progetti front-end compilati.

I vantaggi iniziali sono concreti:

• configurazione più semplice;
• costi spesso nulli o molto bassi;
• HTTPS e CDN già inclusi su molte piattaforme;
• integrazione comoda con GitHub.

Qui strumenti come Vercel, Netlify, Cloudflare e GitHub Pages sono molto utili perché riducono parecchio l’attrito: colleghi il repository, fai push del codice, il servizio esegue la build e pubblica il risultato.

Per iniziare, questo approccio è quasi sempre più chiaro che partire subito da server complessi, VPS, container o configurazioni troppo manuali.

Il flusso più utile da interiorizzare all’inizio è questo:

1. lavori in locale;
2. controlli che il progetto funzioni;
3. fai commit e push su GitHub;
4. il provider rileva la modifica;
5. parte una nuova build;
6. se tutto va bene, il sito aggiornato va online.

Questo modello è prezioso perché separa bene le responsabilità:

• tu curi codice e configurazione;
• GitHub conserva e versiona il progetto;
• l’hosting gestisce pubblicazione e distribuzione.

È anche il motivo per cui Git e GitHub diventano così utili prima del deploy: se la cronologia è ordinata, anche capire cosa ha rotto una build diventa molto più semplice.

Un esempio minimo da tenere in testa

Quando colleghi il repository a un provider, in genere ti verranno chiesti pochi dati:

• repository GitHub da usare;
• branch da pubblicare, spesso main;
• comando di build, per esempio npm run build;
• directory pubblica finale, per esempio dist.

Da lì in poi ogni push sul branch scelto genera un nuovo deploy automatico.

All’inizio puoi vivere bene anche con un URL generato dal provider, ma prima o poi vorrai collegare un dominio tuo.

Qui entrano in gioco i DNS: sono le impostazioni che dicono al dominio dove deve puntare.

Non serve diventare esperti subito, ma conviene fissare tre idee:

• il dominio lo compri da un registrar;
• l’hosting ti dice quali record DNS configurare;
• HTTPS di solito viene emesso automaticamente dopo il collegamento corretto.

Una delle prime fonti di ansia qui è la propagazione DNS. Non sempre il cambio è istantaneo: a volte servono minuti, a volte qualche ora.

Uno degli errori più pericolosi è mettere chiavi API, password o token direttamente nei file tracciati da Git.

In un progetto serio, i dati sensibili vanno gestiti con variabili ambiente, per esempio tramite file .env in locale e impostazioni dedicate lato provider.

Il principio è semplice:

• in locale usi valori non committati;
• online inserisci gli stessi valori nel pannello del servizio di hosting;
• il codice li legge senza esporli nel repository.

Attenzione però: se stai facendo puro front-end statico, alcune variabili finiscono comunque nel bundle client e quindi non sono davvero segrete. Questo è un punto che conviene capire presto.

Quando il sito “in locale va” ma online no, spesso il problema rientra in pochi casi ricorrenti.

• Path asset sbagliati: immagini, CSS o JS puntano a percorsi che online cambiano.
• Build fallita: il provider non riesce a completare il comando di build.
• Variabili ambiente mancanti: in locale c’erano, online no.
• Routing SPA non gestito: refreshando una pagina interna compare 404.
• Dipendenze o versioni Node incoerenti tra locale e hosting.

La cosa utile da imparare non è indovinare. È andare a leggere i log della build e isolare il punto esatto in cui il processo si rompe.

Molto spesso il deploy non fallisce “a caso”: sta dicendo qualcosa, solo che bisogna imparare a leggere quel messaggio con calma.

Prima di considerare un deploy davvero pronto, vale la pena passare da una checklist molto pratica.

• la build locale completa senza errori;
• non ci sono file sensibili nel repository;
• favicon, title e meta base sono presenti;
• link e navigazione funzionano su mobile e desktop;
• 404 o route principali sono gestite correttamente;
• il dominio, se presente, punta al posto giusto;
• il certificato HTTPS è attivo;
• hai controllato almeno una volta la versione pubblicata vera, non solo la preview.

Una volta capito il deploy base, il passo successivo non è per forza complicare tutto. Spesso basta rendere più solido il workflow:

• preview deploy per testare prima del merge;
• branch strategy più chiara;
• controlli automatici di build;
• gestione migliore di dominio, analytics e performance.

La parte importante è che da questo punto in poi il progetto non resta più chiuso nel computer. Entra in una dimensione reale: si visita, si testa, si condivide e si migliora con più criterio.

Se vuoi consolidare il percorso, queste guide si incastrano bene:

• Git pratico senza panico: per la parte locale, commit, branch e recupero errori.
• GitHub operativo: per repository, push/pull e pubblicazione del codice.
• VSCode essenziale: per build, terminale, debug e routine di lavoro più pulita.
• Tutti i tutorial: per seguire gli altri contenuti disponibili.