React
Astro vs Next.js per la documentazione
Astro spedisce zero JavaScript sulle pagine di documentazione, Next.js riusa i Server Components. La scelta dipende da ricerca, versioni e componenti interattivi.
In sintesi
- Astro con Starlight è la via più corta a un sito di documentazione statico con ricerca.
- Next.js conviene quando la documentazione vive accanto a un'applicazione con Server Components.
- Il catalogo EneUI indicizza 1.556 blocchi e 111.985 componenti al 1 novembre 2026: quasi tutti React, quindi in Astro diventano isole.
Per un sito di documentazione Astro è la scelta più diretta: genera HTML statico e non spedisce JavaScript finché un componente non lo chiede. Next.js conviene quando la documentazione è parte di un'applicazione che usa già Server Components.
La documentazione ha requisiti precisi: pagine veloci, indice laterale, ricerca, esempi interattivi e versioni. Astro li copre con Starlight; Next.js li copre con MDX e un po' di configurazione in più.
Due modelli, due costi
| Requisito | Astro + Starlight | Next.js App Router |
|---|---|---|
| Pagina statica | Predefinita, zero JavaScript | Possibile, ma il runtime resta nel progetto |
| Ricerca | Pagefind incluso nel template | Da aggiungere o collegare a un servizio |
| Esempio interattivo | Isola con client:load | Client Component dichiarato |
| Versioni | Cartelle per versione, build separate | Route per versione nello stesso progetto |
La ricerca decide più del framework
Una documentazione senza ricerca è un archivio. Starlight include Pagefind e costruisce l'indice in fase di build, quindi la ricerca funziona senza servizi esterni. In Next.js devi scegliere tra un indice statico, Algolia o un endpoint tuo. Nessuna delle due strade è sbagliata, ma la prima richiede meno lavoro.
Prova in dieci minuti
# Astro docs with the Starlight template
npm create astro@latest docs -- --template starlight
cd docs && npm install && npm run dev
# Next.js docs shell with the App Router
npx create-next-app@latest docs-next --ts --appAggiungi una pagina, una voce di indice e una ricerca. Se la build produce HTML senza JavaScript per il testo, il modello a isole sta funzionando.
Dove vince Astro
- Peso della pagina: il testo è HTML e CSS, il JavaScript arriva solo per le isole.
- Starlight: indice, ricerca, temi e versioni sono già nel template.
- Contenuti tipizzati: le content collection validano frontmatter e slug in build.
Dove vince Next.js
- Un solo progetto: docs e applicazione condividono componenti, tipi e deploy.
- Server Components: gli esempi possono leggere dati reali senza esporre chiavi al browser.
- Ecosistema: MDX, anteprime e registry sono più diffusi e documentati.
Il limite di Astro che il catalogo mostra
Quasi tutti i 111.985 record del catalogo sono React. In Astro li monti come isole, quindi la promessa di zero JavaScript vale per il testo e non per gli esempi: ogni demo interattiva aggiunge il runtime React alla pagina. Se la documentazione ha venti esempi interattivi, il vantaggio si riduce.
Licenze e provenienza
Astro è distribuito con licenza MIT e il repository dichiara la licenza tramite il file del progetto; Next.js è MIT. Starlight fa parte dell'organizzazione Astro. Verifica la licenza del singolo componente che monti, non solo quella del framework.
Nel catalogo: un componente Astro verificato, i blocchi sidebar e 1.556 blocchi con anteprima. Le guide: la direttiva client mancante in Astro e la struttura dell'App Router; il confronto: quanto pesa una libreria UI.
Domande frequenti
Astro è adatto a una documentazione grande?
Sì, se le pagine sono testi e pochi esempi interattivi. Con centinaia di demo pesanti conviene misurare il JavaScript per pagina prima di scegliere.
Starlight supporta la ricerca senza servizi esterni?
Sì, usa Pagefind e costruisce l'indice in fase di build. La ricerca è statica e non richiede un server, ma va rigenerata a ogni build.
Posso usare i componenti React in Astro?
Sì, con l'integrazione React e una direttiva client. Senza direttiva il componente viene reso sul server e non diventa interattivo.
Next.js può generare un sito di documentazione statico?
Sì, con l'export statico o con route prerenderizzate. Perdi alcune funzioni dell'App Router, quindi verifica i requisiti prima di partire.
Quale sceglie un team che ha già Next.js?
Next.js, perché evita un secondo deploy e riusa i componenti. Astro conviene quando la documentazione è un prodotto separato e il peso della pagina è la priorità.