Fumadocs vs Nextra v4 vs Starlight in 2026

TL;DR

Documentation site frameworks have quietly matured into a serious category in 2026. Fumadocs is the fastest-growing option for Next.js teams — it ships with built-in OpenAPI rendering, full-text search via Orama, and a headless component API that makes it dramatically more customizable than Nextra. Nextra v4 is the battle-tested Next.js documentation standard, newly rewritten to use the App Router natively. Starlight (Astro's official docs framework) wins on raw performance — static HTML with zero JavaScript for content pages, and the best Lighthouse scores of the three. Choose based on your stack: Next.js app → Fumadocs; need maximum performance or Astro → Starlight.

Key Takeaways

Fumadocs is the most customizable Next.js docs framework — headless fumadocs-ui components, TypeScript-first content layer, built-in OpenAPI page generation
Nextra v4 is fully rewritten for App Router — drops Pages Router support, now uses React Server Components natively, better performance than v3
Starlight generates pure static HTML — zero JS for content pages, perfect Lighthouse scores, ideal for marketing docs sites and open source projects
Search is table-stakes — all three ship built-in full-text search; Fumadocs and Starlight use client-side Orama/Pagefind; Nextra uses FlexSearch
npm downloads favor Nextra — ~800K/month vs Fumadocs ~150K/month vs Starlight ~350K/month (March 2026)
Fumadocs is gaining fastest — 3x download growth year-over-year; Nextra grew modestly; Starlight doubled

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 are rendered as static HTML with zero client-side JavaScript. The only JavaScript that ships to browsers is for interactive features: the mobile nav toggle, dark mode switch, and search.

The result: Core Web Vitals scores that Fumadocs and Nextra can't match on a comparable content page.

Metric	Starlight	Fumadocs	Nextra v4
LCP (typical)	~0.8s	~1.4s	~1.2s
TBT (typical)	~0ms	~40ms	~30ms
CLS	~0	~0.02	~0.01
JS bundle	~12kB	~85kB	~60kB

Measured on equivalent 50-page documentation sites, Cloudflare CDN, cold cache.

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

Factor	Fumadocs	Nextra v4	Starlight
Framework	Next.js	Next.js	Astro
Architecture	Headless + composable	Opinionated theme	Static-first
npm downloads/mo	~150K	~800K	~350K
OpenAPI support	✅ Built-in	❌	⚠️ Community plugin
Search	Orama (WASM)	FlexSearch	Pagefind
Performance	Good	Good	Excellent
JS bundle	~85kB	~60kB	~12kB
Customizability	✅ High	⚠️ Medium	⚠️ Medium
i18n	✅	✅	✅ Excellent
Community	Growing	Large	Large
v3→v4 migration	N/A	Breaking	N/A
Dark mode	CSS variables	CSS color-scheme	CSS + system
MDX version	MDX 3	MDX 3	MDX 2+

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

Methodology

npm download data from npmjs.com API, March 2026 weekly averages
Performance metrics from WebPageTest on equivalent 50-page documentation sites
Framework versions: Fumadocs 14.x, Nextra 4.x, Starlight 0.32.x
Sources: official documentation, GitHub repos, community Discord servers

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

Fumadocs vs Nextra v4 vs Starlight 2026