Perché abbiamo scelto Astro per il sito di Nightside Labs
Le ragioni tecniche dietro la scelta di Astro: sito statico, contenuti in Markdown e JavaScript solo dove serve.
Il sito di Nightside Labs presenta il laboratorio, raccoglie note tecniche e tiene insieme i prodotti che costruiamo. Il contenuto cambia più spesso del layout. Un server applicativo avrebbe aggiunto processi, aggiornamenti e punti di guasto senza risolvere un problema che avevamo.
Abbiamo scelto di generare pagine HTML durante la build e servirle con nginx. Astro ci ha dato questa struttura senza imporre un runtime JavaScript nel browser.
I requisiti
Volevamo scrivere gli articoli nello stesso repository del sito e rivedere ogni modifica con un diff. Il formato doveva restare leggibile anche fuori dal framework, quindi il blog usa Markdown con pochi dati nel frontmatter: titolo, descrizione, data, tag e stato della bozza.
Volevamo anche una build ripetibile. Chi lavora al progetto deve poter avviare il sito con Docker, senza allineare a mano versioni di Node e dipendenze sulla macchina host. Lo stesso Dockerfile deve produrre l’artefatto che arriva in produzione.
Le pagine pubbliche non richiedono dati aggiornati a ogni richiesta. Prodotti, articoli e testi istituzionali cambiano attraverso il repository. Possiamo quindi prepararli durante la build.
HTML come risultato della build
Astro trasforma i file in src/pages in pagine HTML. I componenti .astro ci permettono di separare header, footer, schede prodotto e parti della home senza consegnare al browser il runtime di un framework.
Il browser riceve markup e CSS per la maggior parte del sito. Così scarichiamo meno codice e possiamo ispezionare l’output. Se una pagina ha un problema, apriamo l’HTML generato e controlliamo cosa è uscito dalla build.
Astro non ci obbliga a rinunciare alle interazioni. Nel sito usiamo script mirati per il cambio di tema, il menu mobile e il movimento della hero durante lo scroll. La pagina prodotti cambia anche il logo di AgendaCore in base al tema. Sono comportamenti circoscritti; non richiedono uno stato applicativo condiviso.
Il blog resta nel repository
Ogni articolo è un file Markdown dentro src/content/blog. Il nome del file diventa lo slug, mentre il frontmatter contiene i dati usati nella lista del blog e nei metadati della pagina.
La content collection descrive quei dati con uno schema. Astro controlla che ogni post abbia titolo, descrizione e data. Lo schema assegna un array vuoto ai tag quando mancano e considera pubblicato un articolo senza il campo draft.
Astro esegue il controllo durante la build. Una data scritta male o un campo del tipo sbagliato fermano il processo prima che nginx riceva i file. Preferiamo trovare un errore nel terminale invece di scoprire una pagina incompleta dopo il rilascio.
Usiamo la stessa collection in due punti del sito. La pagina del blog ordina gli articoli per data; la home prende i tre più recenti. Entrambe escludono i post marcati come bozza. Non dobbiamo mantenere due elenchi o ricordarci di aggiornare una pagina quando pubblichiamo.
Il confine di Docker
Il Dockerfile usa due fasi. Un’immagine Node installa le dipendenze ed esegue astro build. La seconda fase parte da nginx e copia soltanto la cartella dist generata da Astro.
Il container che serve il sito non esegue Node. nginx cerca il file HTML corrispondente all’URL e usa la pagina 404.html quando non lo trova. Il confine tra build e runtime resta visibile anche nel Dockerfile: Node costruisce, nginx serve.
Con le due fasi aggiorniamo il runtime pubblico senza tenere attivo un processo applicativo per mostrare una pagina del blog. Dobbiamo comunque ricostruire e distribuire l’immagine quando cambiamo un articolo, un componente o un foglio di stile.
I costi della scelta
Il flusso editoriale passa da Git. Per pubblicare un articolo bisogna creare un file, controllarlo, fare commit e avviare una nuova build. Oggi questo processo si adatta al modo in cui lavoriamo. Un gruppo editoriale che pubblica più volte al giorno avrebbe bisogno di un’interfaccia diversa.
Il sito non offre anteprime remote delle bozze, pubblicazione programmata o modifiche dal browser. Il campo draft nasconde un articolo dalla build pubblica, ma qualcuno deve cambiare quel valore e distribuire una nuova versione.
Anche le funzioni dinamiche richiedono un sistema separato. Commenti, ricerca su grandi quantità di contenuti o aree riservate introdurrebbero dati e richieste che nginx non può gestire da solo. Se arriveranno, valuteremo il servizio adatto al problema invece di caricare quel lavoro sulle pagine statiche.
La scelta, nel contesto
Astro non è l’unico strumento capace di generare questo sito. Avremmo potuto usare un altro generatore statico o assemblare una pipeline più piccola. Astro ci offre componenti leggibili, contenuti validati e controllo sul JavaScript con poca configurazione.
Per il perimetro attuale lo sceglieremmo ancora. Gli articoli restano file revisionabili, la build produce HTML e il container pubblico ha un solo compito. Se il modo di pubblicare cambierà, rivedremo l’architettura partendo da quel nuovo vincolo.