# Astro vs Next.js for documentation

Astro ships no JavaScript on documentation pages; Next.js reuses Server Components. Search, versioning and interactive examples decide the choice.

> Page: https://ui.eneawork.it/blog/astro-vs-nextjs-documentazione
> Markdown: https://ui.eneawork.it/blog/astro-vs-nextjs-documentazione.md

*2026-11-01*

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

Il 1 novembre 2026 l'endpoint /api/stats di EneUI ha letto 111.985 componenti, 1.556 blocchi e 12.808 icone in 1.472 librerie. Il metodo è una query al catalogo; i blocchi utili a una documentazione stanno nella categoria sidebar, che il catalogo conta insieme agli altri.

## 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 --app

Aggiungi 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

## Dove vince Next.js

## 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.

## FAQ

### 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à.