Configurazione delle isole Astro e React

Per creare un progetto Astro si usa npx create astro@latest, che avvia una procedura guidata interattiva per scegliere un template, le impostazioni di TypeScript e il gestore di pacchetti. Astro supporta diversi template iniziali, tra cui un template vuoto, un template per blog e template per la documentazione.

Le integrazioni di Astro aggiungono il supporto ai framework a un progetto. Eseguendo npx astro add react vengono installati automaticamente @astrojs/react, react e react-dom, e astro.config.mjs viene aggiornato per includere l'integrazione React. L'intera configurazione richiede un solo comando.

Un file .astro è il formato dei componenti di Astro. È composto da una sezione frontmatter (JavaScript racchiuso tra delimitatori ---) e da una sezione template. Per impostazione predefinita, un file Astro produce HTML statico: al browser non viene inviato alcun JavaScript, a meno che non si aggiunga esplicitamente una direttiva client.

Per importare un componente React in un file Astro si usa la sintassi standard dei moduli ES: import Counter from './Counter.jsx'. Senza una direttiva client, Astro esegue il rendering del componente React sul server producendo HTML statico e invia tale HTML al browser: per il componente non viene inviato alcun JavaScript.

Aggiungendo client:visible al tag del componente nel template Astro, il componente diventa un'isola: <Counter client:visible />. Astro invia ora il JavaScript di Counter, lo idrata quando entra nella viewport e lo rende interattivo. Senza la direttiva, rimane HTML statico.

I componenti React usati come isole Astro sono scritti usando React standard: utilizzano hook, stato, effetti e qualsiasi libreria React. All'interno del componente React non esiste alcuna API specifica di Astro. Il confine dell'isola viene definito nel template Astro, non nel codice del componente.

Ogni istanza di un'isola è un albero React indipendente. Due isole Counter nella stessa pagina non condividono lo stato. Se è necessario condividere lo stato, sono disponibili tre opzioni: unirle in un'unica isola, usare i parametri di ricerca dell'URL per uno stato serializzabile oppure usare una libreria di gestione dello stato condiviso come nanostores.

La libreria @nanostores/react fornisce atomi leggeri a cui qualsiasi isola può sottoscriversi. Un'isola scrive in un atomo di nano store e un'altra isola lo legge. Poiché i nano store sono indipendenti dal framework, questo approccio funziona anche tra isole React e Vue nella stessa pagina.

Le raccolte di contenuti di Astro offrono un modo tipizzato per gestire file Markdown e MDX. Si definisce uno schema della raccolta con Zod, si inseriscono i file Markdown in src/content/ e Astro genera funzioni di query completamente tipizzate. Questo è l'approccio standard per articoli di blog, documentazione e pagine di prodotto.

L'esecuzione di astro build genera una cartella dist/ contenente file HTML statici. Per ogni pagina, Astro produce un file HTML con il contenuto renderizzato sul server e solo i bundle JavaScript necessari per le isole presenti in quella pagina. Le pagine senza isole non producono alcun JavaScript.

L'output statico può essere distribuito su qualsiasi CDN (Netlify, Vercel, Cloudflare Pages) senza un server. Per le esigenze di rendering lato server (route dinamiche, endpoint API), Astro supporta adattatori SSR per Node.js, Vercel Edge, Cloudflare Workers e Deno. Le isole funzionano allo stesso modo in entrambe le modalità.

Qual è la modifica minima da apportare a un componente React importato in un template Astro per renderlo interattivo sul client?

Configurare Astro con React usando npx astro add react. I file Astro sono statici per impostazione predefinita; aggiungendo una direttiva client: al tag di un componente React, questo diventa un'isola idratata. I componenti React sono normali componenti React e non usano API specifiche di Astro. Lo stato è isolato per ogni isola; nanostores consente la comunicazione tra isole. La build produce HTML statico con solo il JavaScript necessario per le isole.