--- og_image: "/images/guides/fumadocs-vs-nextra-v4-vs-starlight-documentation-sites-2026.webp" title: "Fumadocs vs Nextra v4 vs Starlight 2026: Which Wins?" description: "Fumadocs vs Starlight vs Nextra in 2026: compare Next.js fit, Astro performance, docs search, OpenAPI support, and content-model trade-offs." date: "2026-03-09" author: "PkgPulse Team" tags: ["documentation", "nextjs", "astro", "fumadocs", "nextra"] --- ## TL;DR If your search is **Fumadocs vs Starlight**, choose by stack first. **Fumadocs** is the stronger fit when docs live inside a Next.js product, need custom UI composition, or need OpenAPI-driven reference pages. **Starlight** is the stronger fit when the docs can be an Astro site and you want a static-first documentation system with excellent default performance and built-in i18n. **Nextra v4** remains the conservative Next.js docs-framework choice when you want an opinionated, battle-tested theme rather than Fumadocs' more composable/headless approach. ## Key Takeaways - **Fumadocs is the most customizable Next.js option** — `fumadocs-core`, `fumadocs-ui`, MDX tooling, and OpenAPI packages let product teams compose docs into an existing app. - **Nextra v4 is the opinionated Next.js theme path** — use it when a standard docs layout is a feature, not a limitation. - **Starlight is the static-first Astro path** — strong default performance, content collections, Pagefind search, and polished i18n make it ideal for standalone docs. - **Search is table-stakes** — verify the current search package and hosting model rather than assuming old Orama/Pagefind/FlexSearch claims still match your setup. - **npm downloads are package-name dependent** — current npm API checks show Fumadocs core/UI, Nextra/theme packages, and Starlight all have meaningful usage; do not use one frozen monthly number as the decision. --- ## Why Documentation Frameworks Matter Writing docs in raw Next.js or Astro means re-solving the same problems every time: sidebar navigation from your file system, full-text search across pages, syntax highlighting in code blocks, breadcrumbs, table of contents, dark mode, mobile responsive layout, and SEO meta tags. Documentation frameworks solve these once, letting you focus on content. The three dominant options in the TypeScript ecosystem each take a different approach: - **Fumadocs**: Next.js app with a headless component kit — you compose the docs UI from primitives - **Nextra v4**: Next.js app with an opinionated theme layer — you configure rather than compose - **Starlight**: Astro-based static site generator — file-based, content-first, zero-JS by default --- ## Fumadocs [Fumadocs](https://www.fumadocs.dev/) (by Fuma Nama) emerged as the serious alternative to Nextra for Next.js teams who need documentation as part of a larger web application — not a standalone site. ### Architecture Fumadocs separates concerns cleanly: - **`fumadocs-core`** — the data layer: reads your MDX files, builds the page tree, handles search indexes - **`fumadocs-ui`** — the UI layer: pre-built headless components for sidebar, TOC, breadcrumbs, code blocks - **`fumadocs-mdx`** — MDX configuration: remark/rehype plugins, frontmatter schema, TypeScript types for content - **`fumadocs-openapi`** — OpenAPI generator: converts your OpenAPI spec into documentation pages automatically The headless approach means you can use the built-in `fumadocs-ui` theme or compose your own UI from `fumadocs-core` primitives. If your docs need to match a custom design system, Fumadocs handles it without fighting the library. ### Standout Features **Built-in OpenAPI rendering.** `fumadocs-openapi` converts an OpenAPI 3.x spec into documentation pages — endpoints, parameters, request/response schemas, code examples in multiple languages, and a live "Try it" panel. This is weeks of work in any other documentation framework. ```bash npx fumadocs-openapi generate ./openapi.json -o ./content/api ``` It outputs MDX files for every endpoint, organized by tag. The generated pages stay in sync with your spec file. **Orama full-text search.** Fumadocs ships [Orama](https://orama.com) integration out of the box — a WASM-powered in-browser search index. Results appear instantly without a network request after the initial page load. For documentation sites where search is the primary navigation mechanism, this is materially better than server-round-trip search. **TypeScript content schema.** Content is typed via a Zod-based schema: ```typescript // source.config.ts import { defineConfig, defineDocs } from 'fumadocs-mdx/config' import { z } from 'zod' export default defineConfig({ docs: defineDocs({ schema: z.object({ title: z.string(), description: z.string().optional(), icon: z.string().optional(), }), }), }) ``` TypeScript errors catch missing required frontmatter fields at build time — not at runtime. **I18n built-in.** Multi-language documentation with route-based locale prefixes (`/en/docs`, `/fr/docs`) works without configuration. The sidebar navigation updates per-locale automatically. ### What Teams Use Fumadocs Fumadocs is most common in: - AI API companies documenting REST APIs with OpenAPI specs - SaaS products embedding docs in their Next.js app (shared layout, auth-gated docs) - Developer tools where the docs are part of the product site ### Fumadocs Limitations - **Smaller community than Nextra** — fewer examples, fewer third-party themes, less Stack Overflow coverage - **More setup than Nextra** — the headless approach requires more initial configuration; you're assembling rather than using defaults - **Next.js only** — if you ever move off Next.js, you need to migrate docs too --- ## Nextra v4 [Nextra](https://nextra.site) has been the dominant Next.js documentation framework since 2021 and ships documentation for Vercel, SWR, tRPC, and many other major OSS projects. Version 4, released in 2024, was a full rewrite to support the App Router. ### What Changed in v4 Nextra v3 used the Pages Router with a custom `_app.tsx` wrapper and a theme config file. v4 is rebuilt from scratch for the App Router: - **`app/layout.tsx` instead of `pages/_app.tsx`** — standard App Router layout wrapping - **React Server Components** — page content renders on the server; only interactive elements (search, sidebar state, dark mode toggle) use client components - **Removed `next-themes` dependency** — dark mode is now handled via CSS `color-scheme` without a React provider - **Smaller bundle** — RSC rendering means less JavaScript shipped to the browser The migration from v3 to v4 is breaking — directory structure, config format, and theme API all changed. Nextra explicitly documents this as a rewrite rather than an upgrade. ### The Docs Theme Nextra's `nextra-theme-docs` is the most battle-tested documentation theme in the Next.js ecosystem. It ships with: - File-system sidebar generation with `_meta.json` for ordering and titles - Auto-generated table of contents from headings - Full-text search via FlexSearch (client-side, no backend required) - Built-in code block syntax highlighting via Shiki - Dark/light mode with system preference detection - Responsive mobile layout with drawer sidebar - SEO meta tags and Open Graph images For a standard API reference or usage guide, Nextra's defaults are production-quality without customization. ### Configuration Pattern ```json // _meta.json (in each directory) { "index": "Introduction", "getting-started": "Getting Started", "api-reference": { "title": "API Reference", "type": "folder" } } ``` Sidebar ordering, page titles, separators, and external links are all configured via `_meta.json` files alongside content. It's declarative and readable but less flexible than Fumadocs' TypeScript schema approach. ### What Teams Use Nextra The most established brands: **Vercel** (internal docs), **tRPC** (official docs), **Prisma** (some sections), **SWR** (official docs). If you see a documentation site with that particular sidebar-nav-on-left, content-center, TOC-on-right layout, it's probably Nextra. ### Nextra v4 Limitations - **Less customizable than Fumadocs** — the theme layer is opinionated; deep customizations require overriding theme internals - **No built-in OpenAPI rendering** — you need a separate library if you're documenting an API - **FlexSearch vs Orama** — FlexSearch is older, less accurate for fuzzy matching than Orama - **v3 → v4 is a breaking migration** — existing Nextra sites can't upgrade without significant work --- ## Starlight [Starlight](https://starlight.astro.build) is Astro's official documentation framework, released in 2023 and now the documentation standard for the entire Astro ecosystem. ### The Astro Advantage Starlight's architecture is fundamentally different from Fumadocs and Nextra — it's an **Astro integration**, not a Next.js framework. Content pages can be rendered as static HTML, while client-side JavaScript is reserved for interactive features such as navigation state, dark mode, and search. That architecture gives Starlight the strongest default performance posture of the three, especially for standalone documentation sites where most pages are static reading experiences. Treat it as an architectural advantage rather than a universal benchmark: verify your own site with Lighthouse, WebPageTest, or your production RUM data after enabling the search, analytics, and interactive components you actually plan to ship. ### Pagefind Search Starlight uses [Pagefind](https://pagefind.app) for full-text search — a Rust-compiled WASM binary that indexes your static HTML at build time and serves search from pre-built indexes without any server. No API calls, no backend, just static files. For sites deployed to Netlify, Vercel, or GitHub Pages, Pagefind means zero ongoing search infrastructure cost regardless of traffic volume. ### MDX and Content Collections Starlight integrates with [Astro Content Collections](https://docs.astro.build/en/guides/content-collections/) for type-safe frontmatter. Content is validated at build time against a Zod schema, with TypeScript types generated for your content model. ### i18n and Translations Starlight has the best built-in i18n support of the three — locale detection, RTL language support (Arabic, Hebrew, Persian), and a UI translation system that lets community members contribute translations for the built-in UI text (buttons, labels, etc.). The [i18n component library](https://starlight.astro.build/guides/i18n/) includes a ``, ``, ``, and other components that automatically translate when the locale changes. ### What Teams Use Starlight The Astro ecosystem (official Astro docs), the Biome linter docs, Cloudflare Workers docs, and a growing number of open source projects that prioritize SEO and performance over customization flexibility. ### Starlight Limitations - **Astro-only** — if your product is Next.js, you're running a separate build system for docs - **Less extensible than Fumadocs** — Starlight's component override system is good but more limited than Fumadocs' headless approach - **No OpenAPI generator** — you need `@astrojs/starlight-openapi` (community plugin) for API documentation - **Astro learning curve** — teams already proficient in Next.js have a framework context switch --- ## Side-by-Side Comparison | Factor | Fumadocs | Nextra v4 | Starlight | |--------|----------|-----------|-----------| | Framework | Next.js | Next.js | Astro | | Architecture | Headless/composable docs toolkit | Opinionated docs theme/site generator | Static-first Astro integration | | Best fit | Product docs inside a Next.js app; API reference docs | Conventional Next.js docs with minimal theme work | Standalone open-source or product docs where static output matters | | Current package line checked | `fumadocs-core` / `fumadocs-ui` 16.x | `nextra` / `nextra-theme-docs` 4.x | `@astrojs/starlight` 0.39.x | | OpenAPI support | First-party `fumadocs-openapi` package | Bring another tool | Community plugin ecosystem | | Search posture | Fumadocs search integrations; verify Orama package/docs for your setup | Theme-provided local search | Pagefind-backed static search | | Performance posture | Good, depends on Next.js app shell | Good, depends on Next.js app shell | Strongest default static posture | | Customizability | High | Medium | Medium | | i18n | Supported | Supported | Strong built-in docs/i18n story | | Migration risk | More assembly decisions | v3→v4 breaking changes to plan | Astro context switch if your app is Next.js | --- ## How to Choose **Choose Fumadocs if:** - You're building a Next.js app with embedded documentation (shared auth, layout, or design system) - You need OpenAPI documentation generated from a spec file - You want maximum control over the docs UI without building from scratch - You can tolerate a smaller community and less out-of-the-box defaults **Choose Nextra v4 if:** - You want the most battle-tested Next.js documentation solution - Your team already knows Nextra v3 (despite the breaking migration, the concepts carry) - You want to match the documentation style of tRPC, SWR, or other major OSS projects - You prefer opinionated defaults over headless customization **Choose Starlight if:** - Performance and Lighthouse scores are non-negotiable - You're already using Astro for your site - You're building open source project documentation that needs i18n and community contributions - You're deploying to static hosting (GitHub Pages, Netlify, Cloudflare Pages) and want zero runtime cost ## Sources checked Current source checks during this refresh (accessed 2026-05-16): - [Fumadocs official site](https://www.fumadocs.dev/), [Fumadocs UI docs](https://www.fumadocs.dev/docs/ui), [Fumadocs Headless docs](https://www.fumadocs.dev/docs/headless), and [Fumadocs OpenAPI docs](https://www.fumadocs.dev/docs/openapi) — architecture, UI/headless positioning, and OpenAPI workflow. - [`fumadocs-core`](https://www.npmjs.com/package/fumadocs-core) and [`fumadocs-ui`](https://www.npmjs.com/package/fumadocs-ui) npm metadata — current package line and package-level usage signal. - [Nextra official site](https://nextra.site/) and [Nextra docs](https://nextra.site/docs) — Next.js/MDX docs framework positioning. - [`nextra`](https://www.npmjs.com/package/nextra) and [`nextra-theme-docs`](https://www.npmjs.com/package/nextra-theme-docs) npm metadata — current package line and package-level usage signal. - [Starlight official docs](https://starlight.astro.build/), [Starlight i18n guide](https://starlight.astro.build/guides/i18n/), and [Astro content collections](https://docs.astro.build/en/guides/content-collections/) — static-first docs architecture, i18n, and content schema posture. - [`@astrojs/starlight`](https://www.npmjs.com/package/@astrojs/starlight), [Pagefind](https://pagefind.app/), and [Orama](https://orama.com) — package/search-source checks for the current documentation-search references used in this guide. --- *Compare all documentation-related npm packages on [PkgPulse](/compare/fumadocs-vs-nextra) — download trends, bundle sizes, and health scores updated daily.* *Related: [Docusaurus vs VitePress vs Nextra vs Starlight 2026](/guides/docusaurus-vs-vitepress-vs-nextra-vs-starlight-2026) · [Contentlayer vs Velite vs next-mdx-remote 2026](/guides/contentlayer-vs-velite-vs-next-mdx-remote-mdx-content-2026)*