React
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.
Key points
- Astro with Starlight is the shortest path to a static documentation site with search.
- Next.js pays off when documentation lives beside an application that already uses Server Components.
- The EneUI catalogue indexes 1,556 blocks and 111,985 components on 1 November 2026, almost all React, so in Astro they become islands.
For a documentation site Astro is the most direct choice: it generates static HTML and ships no JavaScript until a component asks for it. Next.js pays off when the docs are part of an application that already uses Server Components.
Documentation has precise requirements: fast pages, a side index, search, interactive examples and versions. Astro covers them with Starlight; Next.js covers them with MDX and a little more configuration.
Two models, two costs
| Requirement | Astro + Starlight | Next.js App Router |
|---|---|---|
| Static page | The default, zero JavaScript | Possible, but the runtime stays in the project |
| Search | Pagefind included in the template | Add one or connect a service |
| Interactive example | Island with client:load | Declared Client Component |
| Versions | Folder per version, separate builds | Route per version in the same project |
Search decides more than the framework
Documentation without search is an archive. Starlight bundles Pagefind and builds the index at build time, so search works with no external service. In Next.js you choose between a static index, Algolia or your own endpoint. Neither route is wrong, but the first takes less work.
Try it in ten minutes
# 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 --appAdd one page, one index entry and one search. If the build produces HTML without JavaScript for the text, the island model is working.
Where Astro wins
- Page weight: the text is HTML and CSS, and JavaScript arrives only for islands.
- Starlight: index, search, themes and versions are already in the template.
- Typed content: content collections validate frontmatter and slugs at build time.
Where Next.js wins
- One project: docs and application share components, types and deployment.
- Server Components: examples can read real data without exposing keys to the browser.
- Ecosystem: MDX, previews and registries are more common and better documented.
The Astro limit the catalogue shows
Almost all 111,985 catalogue records are React. In Astro you mount them as islands, so the zero-JavaScript promise covers the text and not the examples: every interactive demo adds the React runtime to the page. If the docs carry twenty interactive examples, the advantage shrinks.
Licences and provenance
Astro ships under the MIT licence and the repository declares it in the project file; Next.js is MIT. Starlight belongs to the Astro organisation. Check the licence of the single component you mount, not only the framework licence.
In the catalogue: a verified Astro component, sidebar blocks and 1,556 blocks with previews. The guides: the missing client directive in Astro and the App Router structure; the comparison: how much a UI library weighs.
Frequently asked questions
Is Astro suitable for large documentation?
Yes, when pages are text and a few interactive examples. With hundreds of heavy demos, measure the JavaScript per page before you choose.
Does Starlight search work without external services?
Yes. It uses Pagefind and builds the index at build time. Search is static and needs no server, but it must be rebuilt with every deployment.
Can I use React components in Astro?
Yes, with the React integration and a client directive. Without a directive the component renders on the server and stays inert.
Can Next.js generate a static documentation site?
Yes, with static export or prerendered routes. You lose some App Router features, so check the requirements before you start.
Which one does a team already on Next.js pick?
Next.js, because it avoids a second deployment and reuses components. Astro pays off when documentation is a separate product and page weight is the priority.