Come fare il deployment di un'app su GitHub Pages?

Fondamentalmente è quello, però voglio aggiungere un dettaglio che mi è stato utile quando ho iniziato a fare deployment. Come detto sopra la base è giusta, ma dipende molto da quello che stai deployando. Se è un sito statico semplice, tipo HTML, CSS e JavaScript vanilla, letteralmente basta pushare il codice e attivare Pages dalle settings - scegli se vuoi che legga dalla branch main e dalla cartella root, oppure da una cartella /docs. Fatto.

Ma se usi React o Vue, la cosa cambia un po'. Devi installare il pacchetto `gh-pages` con npm, poi configurare il `package.json` aggiungendo `"homepage": "https://tuousername.github.io/nome-repo"` (importante mettere il nome del repo se non è il tuo sito principale). Dopo di che aggiungi gli script di build e deploy, tipo `"deploy": "npm run build && gh-pages -d build"` per React. Quando runni `npm run deploy`, il tool compila tutto e pushes automaticamente la cartella build sulla branch `gh-pages`. Dalle settings attivi Pages su quella branch e sei a posto.

Un'altra cosa che ho imparato facendo vari tentativi: se hai asset o immagini che non caricano, spesso è un problema di percorsi relativi. Verifica bene che le immagini siano linkate in modo corretto nel tuo codice. E se usi un router (tipo React Router), devi configurarlo con `basename` per il nome del repo, altrimenti i link non funzionano. È uno di quei dettagli che scopri quando vedi tutto rotto in produzione, haha.

Esatto, quello che hanno detto è giusto. Io aggiungerei solo che se hai un sito statico semplice (html, css, js) non devi nemmeno fare nulla di particolare, basta che il repo sia pubblico e che attivi Pages dalle impostazioni pointing alla branch che vuoi, di solito main.

Per React e simili devi installare `gh-pages` e mettere gli script giusti nel package.json tipo `"deploy": "gh-pages -d build"`, poi quando fai `npm run deploy` carica tutto in automatico.

Una cosa che nessuno dice ma è davvero utile: se il tuo progetto non è nella root del repo, devi specificare la cartella giusta nelle settings di GitHub Pages (scegli "Deploy from a branch" e seleziona la cartella `/docs` o `/dist` a seconda di dove finisce la build).

Io l'ho scoperto sulla mia pelle quando ho deployato un sito a fianco ad altri progetti nello stesso repo e mi son trovato con una pagina vuota.

Ah, e un trick che uso spesso: crea un workflow GitHub Actions semplice che fa il build automatico quando pussi, così non devi fare manualmente `npm run build` e poi commitare la cartella compilata - lasci che GitHub lo faccia per te e la gestione diventa molto più pulita.

La cosa più importante è capire che GitHub Pages richiede che tu scelga quale cartella servire come root del sito, e il 90% dei problemi viene da lì. Non è intuitivo: molti caricano tutto il repo e poi si chiedono perché non vede nulla. Quando ho messo online il primo progetto fatto con Vite, ho perso ore perché avevo il file index.html nella cartella dist, ma GitHub Pages cercava nella root.

Quello che io farei è: crea il repo, fai il push del tuo codice, poi vai in Settings > Pages. Lì seleziona il branch (di solito main) e specifica la cartella esatta dove sono i file che vuoi servire (nella maggior parte dei casi è / per la root, oppure /docs o /dist se usi un bundler). Se usi React, Vue o simili, devi prima lanciare il build locale per generare i file statici finali, fare il commit di quei file e solo dopo attivarli su Pages.

Un dettaglio che mi ha salvato dopo: se vuoi che il deploy sia automatico ogni volta che fai push, puoi usare una GitHub Action. È più avanzato, ma evita di dover fare il build manualmente ogni volta. Nei primi tempi facevo tutto a mano e ogni tanto dimenticavo di committare la build. Ora uso uno script semplice che lo fa per me e non ci penso più.