Fumadocs vs Nextra v4 vs Starlight 2026: Which Wins?

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

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 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:

// 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 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

// _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 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 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 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 includes a <LinkButton>, <Badge>, <Steps>, 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

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, Fumadocs UI docs, Fumadocs Headless docs, and Fumadocs OpenAPI docs — architecture, UI/headless positioning, and OpenAPI workflow.
• fumadocs-core and fumadocs-ui npm metadata — current package line and package-level usage signal.
• Nextra official site and Nextra docs — Next.js/MDX docs framework positioning.
• nextra and nextra-theme-docs npm metadata — current package line and package-level usage signal.
• Starlight official docs, Starlight i18n guide, and Astro content collections — static-first docs architecture, i18n, and content schema posture.
• @astrojs/starlight, Pagefind, and Orama — package/search-source checks for the current documentation-search references used in this guide.

Compare all documentation-related npm packages on PkgPulse — download trends, bundle sizes, and health scores updated daily.

Related: Docusaurus vs VitePress vs Nextra vs Starlight 2026 · Contentlayer vs Velite vs next-mdx-remote 2026