01. Fondamenta e modello mentale

< Indice · successivo → 02 - Progetto, componenti e stili

1.1 Il problema che Astro risolve

Un sito fatto con un framework client-side classico (Next.js in modalità app, SvelteKit, Nuxt) spedisce al browser l’HTML più il JavaScript necessario a ri-costruire quella stessa pagina lato client (idratazione). Per un’applicazione, dashboard, editor, gestionale, è un costo sensato: l’interattività è ovunque.

Per un sito content-driven, blog, documentazione, guide, sito vetrina, quel costo è quasi tutto sprecato: il 95% della pagina è testo che non fa nulla.

Astro parte dal presupposto opposto: il default è HTML senza JavaScript, e l’interattività si aggiunge in modo esplicito, pezzo per pezzo. La rivendicazione del progetto è “40% più veloce con il 90% di JavaScript in meno” rispetto all’equivalente React; il numero vale quel che vale, il principio architetturale è solido.

📖 Why Astro

1.2 Island architecture

Il concetto centrale. Il termine è di Katie Sylor-Miller (Etsy, 2019), formalizzato da Jason Miller di Preact.

L’idea: la pagina è un oceano di HTML statico in cui galleggiano poche isole interattive. Ogni isola:

• viene renderizzata a HTML dal server (quindi è visibile e indicizzabile subito);
• carica il proprio JavaScript in modo indipendente dalle altre;
• può decidere quando caricarlo (subito, quando il browser è libero, quando entra nel viewport, mai).

Conseguenza pratica: una pagina con 5 isole non ha “un bundle” ma 5 bundle piccoli e indipendenti. Se una fallisce o è lenta, le altre funzionano.

Ci sono due famiglie di isole:

• client island: codice che gira nel browser. Si attiva con una direttiva client:* su un componente React/Svelte/Vue/Solid/Preact. → 05 - Interattività - island, script e view transitions
• server island: un componente .astro con server:defer, renderizzato on demand sul server e iniettato nella pagina dopo. Serve per i pezzi personalizzati (avatar utente, prezzo aggiornato, carrello) dentro una pagina altrimenti statica e cacheabile. → 06 - Rendering on-demand - adapter, middleware, actions

📖 Islands architecture

1.3 Server-first, MPA, non SPA

Astro è dichiaratamente multi-page: ogni URL è un documento HTML, la navigazione è una navigazione del browser. Non c’è un router client obbligatorio, non c’è uno stato applicativo globale che sopravvive tra le pagine.

Questo è un vincolo, non un dettaglio. Se ti serve stato che attraversa le pagine puoi aggiungere <ClientRouter /> (modulo 5), ma è un’aggiunta opzionale, non il modello base.

Il test che vale

Astro è la scelta giusta se il contenuto è il prodotto. Blog, documentazione, guide, marketing, portfolio, e-commerce vetrina, landing. Astro è la scelta sbagliata se l’interfaccia è il prodotto. Editor collaborativi, dashboard con stato condiviso ovunque, app con navigazione interna intensiva. In quel caso stai combattendo contro il framework: usa qualcos’altro.

1.4 Statico o on-demand: la decisione che ti segue ovunque

Due modalità di rendering, che convivono nello stesso progetto:

• Prerendering (statico): la pagina viene generata a build time, una volta, e servita come file HTML. È il default.
• On-demand (SSR): la pagina viene generata a ogni richiesta, sul server. Richiede un adapter (Node, Netlify, Vercel, Cloudflare).

Si configura globalmente:

// astro.config.mjs
export default defineConfig({
  output: 'static',   // default. L'alternativa è 'server'
});

E si sovrascrive per singola rotta:

---
export const prerender = false;   // questa pagina è on-demand
---

Dalla documentazione, testualmente: “The 'server' output mode does not bring any additional functionality. It only switches the default rendering behavior.” Il consiglio ufficiale, condivisibile, è restare su 'static' e fare opt-out sulle poche rotte che ne hanno davvero bisogno.

Cambiato da Astro 4

output: 'hybrid' non esiste più (rimosso in Astro 5): quel comportamento è oggi il default di 'static'. Se leggi un tutorial che dice “metti hybrid”, è vecchio. Inoltre prerender accetta solo true/false letterali: niente più valori dinamici tipo export const prerender = import.meta.env.QUALCOSA.

📖 On-demand rendering

1.5 Cosa metti dentro Astro

Astro non ti obbliga a scegliere un framework UI. Puoi:

• non usarne nessuno (componenti .astro + un po’ di <script>);
• usarne uno (React, Svelte, Vue, Solid, Preact, Alpine);
• usarne più di uno nella stessa pagina: con il limite che solo un file .astro può contenere componenti di framework diversi.

Nella pratica: per una guida o un sito di documentazione, nella maggior parte dei casi non ti serve alcun framework UI. Un web component da 15 righe copre il 90% dei casi (menu, toggle, copia-negli-appunti, tab). Aggiungi React solo quando hai bisogno di una libreria React specifica.

1.6 Installazione e primo progetto

Requisito: Node >= 22.12.0. ✅ verificato: [email protected] dichiara "engines": { "node": ">=22.12.0" }.

npm create astro@latest

Il wizard chiede template, TypeScript, git. Flag utili per saltarlo:

npm create astro@latest -- --template blog --add mdx --install --git --yes

Comandi del ciclo di vita:

Comando	Cosa fa
astro dev	dev server con HMR
astro build	build di produzione in dist/
astro preview	serve dist/ localmente, per controllare la build
astro check	type-check dei file .astro (esce con codice 1 se ci sono errori)
astro sync	rigenera i tipi TypeScript (.astro/types.d.ts)
astro add <nome>	installa e configura un’integrazione
astro info	dump dell’ambiente, da allegare ai bug report

Novità utili di Astro 7: astro dev --background avvia il dev server come processo staccato, con astro dev status | stop | logs. È pensato per gli agenti AI, ma è comodo anche a mano.

📖 Install and setup · CLI reference

1.7 Il modello mentale in cinque righe

1. Ogni file in src/pages/ è un URL.
2. Il codice tra i --- in cima a un file .astro gira solo sul server, mai nel browser.
3. Tutto il resto è HTML, e viene spedito senza JavaScript.
4. Se vuoi JavaScript nel browser, devi chiederlo esplicitamente (<script> o client:*).
5. Il contenuto strutturato (Markdown) si gestisce con le content collections, non a mano.

Se hai capito questi cinque punti, il resto del corso è dettaglio.

Esercizi

1. Crea un progetto vuoto (npm create astro@latest, template “Empty”), avvia astro dev, apri il browser, guarda il sorgente della pagina. Conta i tag <script>.
2. Fai astro build e apri dist/index.html. Confronta il peso con la home di un sito Next.js qualsiasi (DevTools → Network → filtro JS).
3. Scrivi in due righe, per il tuo prossimo progetto reale, perché Astro è o non è la scelta giusta. Se la risposta è “perché è veloce”, non hai risposto.