Upgrade to Next.js 16 / Nextra 4 / React 19

[apbendi]

Coupled major-version upgrade. These can't be done independently:

Package	Current	Target
next	14.2.x	16.x
nextra	3.3.x	4.x
nextra-theme-docs	3.3.x	4.x
react / react-dom	18.3.x	19.x
@types/react	18.x	19.x

Nextra 4 requires Next.js 15+, which requires React 19 — so all four must move together.

Migration scope

Nextra 4 is not a drop-in bump. The substantive changes:

• App Router instead of Pages Router. Move all content from pages/ to content/. The catch-all route lives under app/.
• mdx-components.tsx at the repo root becomes the canonical place for component overrides. Today our overrides sit in theme.config.tsx's components field (light- and dark-mode-aware Link, Embed, Columns, Column).
• _meta.{js,jsx,ts,tsx} files survive but with some behavior changes (e.g. how display: \"children\" and display: \"hidden\" interact with the App Router).
• theme.config.tsx schema has shifted slightly (banner, footer, search props).
• Migration scripts in scripts/ (migrate-content.mjs, build-meta.mjs, promote-folder-indexes.mjs, etc.) were tailored to the Pages Router tree and would not match the new directory structure. They're historical now; not load-bearing for the upgrade itself.

Next.js 15→16 has changes around async params and default caching, but for a static-export docs site (output: \"export\") most of those don't apply.

Verification checklist

• pnpm build succeeds
• Pages render at the same URLs as today
• Sidebar nav (with collapse / expand-with-index-link / display:children behavior) intact
• FlexSearch search box works
• Top banner renders with pale-yellow background and links open in new tab
• Custom components in MDX still work: <Callout>, <Embed>, <Columns>/<Column>, <Steps>
• prose-link styling on internal/external links survives
• CI link check (.github/workflows/pr-check.yml) still passes against the new build output
• Vercel preview deploy looks identical to current main

Why this is worth doing eventually

No functional bug today; benefits are: current versions, Nextra 4's improved theming and search, React 19 features available if we ever need them, no looming EOL concerns.

Why this isn't urgent

Nothing's broken on Nextra 3. Estimated effort: ~half a day if the content moves cleanly; longer if any of the custom-component overrides need rework.

[apbendi]

While working in v3 we ran into a related sidebar UX issue worth noting for the v4 migration:

In v3, the active folder cannot be manually collapsed. Clicking its chevron sets the closed state, but a useEffect in nextra-theme-docs immediately re-opens it whenever a descendant is on the active route (nextra-theme-docs/dist/index.js:1549–1573). It reads as a broken chevron.

As a partial workaround we set sidebar.autoCollapse: true in theme.config.tsx — that auto-closes other folders when you navigate away, which cleans up the sidebar but doesn't fix the click-to-collapse-the-active-folder problem.

To do as part of this upgrade:

• Verify whether v4's redesigned sidebar fixes the active-folder collapse behavior.
• If it does, drop autoCollapse: true and re-evaluate the default sidebar behavior from scratch (collapse defaults, expand-on-hover, etc.). The v3 choice was driven by working around a limitation, not by independent preference.
• If v4 still has the same limitation, consider whether autoCollapse: true still feels right under v4's new defaults or whether something else fits better.