Migrate website from Nextra v2 to Nextra v4

[mnapoli]

Upgrade website/ from Nextra 2.13 to Nextra 4. This is 3 stacked migrations: Nextra 2→4 API, Next.js Pages Router→App Router (v4 is App Router only, theme.config.jsx no longer exists), Tailwind 3→4 (required by nextra-theme-docs v4).

Site inventory: 86 MDX pages, 15 _meta.json, ~50 files importing Nextra components, ~44 files using next-seo, 140-line theme.config.jsx, custom marketing pages (home, /cloud/*, /news, sponsors/testimonials via GitHub API), Algolia DocSearch, next-sitemap, next-plausible proxy, middleware, redirects.js, /api/md rewrite (Markdown for AI crawlers), link-checker/. Note: docs source lives in top-level docs/, synced into website/src/pages/docs/ by the website Makefile.

Full Phase 0 migration map: see audit comment.

Decisions

• Search: replace Algolia DocSearch with Pagefind (v4 default), docs-only index (exclude marketing pages). Reversible via custom search prop on theme Layout. Accepted losses: search analytics, typo tolerance, no search in next dev.
• Docs design: adopt v4 default look, no pixel-matching. Matthieu reviews side-by-side screenshots before merge; big differences not acceptable.
• Redirects: hard requirement. Any URL change must be flagged + get a redirect. Verify by crawling all current prod sitemap URLs against new build → assert 200-or-redirect. Hash-fragment redirects (~30, client-side) must be reimplemented in App Router.
• Remote MDX: removed via prep PR Inline AWS CDK docs instead of fetching them remotely #2131 (inlined constructs README; future updates manual).

Plan

• Prep PR Inline AWS CDK docs instead of fetching them remotely #2131: inline constructs README, drop nextra/remote — merged
• Phase 0 — audit: migration map
• Phase 1 — spike: all 6 unknowns answered, working build — spike report. Scaffold reusable: branch worktree-agent-a61252823a9d0f300, website/spike/, commit 5ce77963
• Decision: fresh v4 scaffold + port content (in-place would leave repo unbuildable throughout; scaffold doesn't survive the v2→v4 cut). Reuse the spike skeleton
• Phase A — fresh v4 scaffold in website/ (PR Migrate website to Nextra 4 #2132, build green): app/layout with full theme.config port, catch-all route + metadata, Tailwind v4 + brand palette, hash-redirect client component, middleware (moved to website root), .md route handler, Makefile sync retargeted to content/docs. Old pages staged in website/_port/pages/
• Phase B — bulk docs content: 67 source docs swept, 13+2 _meta converted, full sync active, build green. URL parity: 70/70 live /docs/* URLs present. Extras: fixed icon import paths broken by the dir move (5 files), extracted serverless-costs calculator to a 'use client' component. Note: some internal .mdx-suffixed links 404 — pre-existing on live prod, not a regression (follow-up candidate)
• Phase C — marketing/custom pages: all ported, build green (94 pages). Sitemap parity 91/91 vs live, 0 missing 0 extra. All routes curl-verified 200. Notes: /cloud/* per-component routes were accidental v2 pages, recreated as thin wrappers for parity (candidate to remove+redirect later); credits data now revalidates hourly instead of build-only (harmless); changelog kept as MDX + async Server Component
• Phase D — Pagefind docs-only via CLI glob (70/70 index entries are /docs/*); plumbing verified: .html+path redirects 308-correct, hash-redirect coverage confirmed by static analysis, .md+content negotiation pass, sitemap 91/91 + robots byte-identical to live, Plausible proxy config identical, trailing-slash identical to live. Bug fixed: JSX comments leaked into .md crawler output
• Phase E — verification: zero regressions vs prod. 91/91 sitemap URLs, 71/72 redirects + 5 .html pattern (1 failure pre-existing on prod), 66/70 .md endpoints (4 failures pre-existing on prod), browser tests 5/5 (hash redirects, docs-only search, calculator/pricing/tabs), 24 side-by-side screenshots captured
• Review fixes (commit e4acf3f): independent code review found 0 high-severity issues; applied 6 fixes — /docs broken .md alternate link (only true regression), path-traversal hardening in md route, .md-source fallback (3 pages now work, 404 on prod), /docs.md now serves markdown (404 on prod), revived dead /docs/web-apps* redirects (404 on prod), removed 41 dead hash entries from server redirects
• Matthieu's visual review round 1: new build looks different from prod → full visual audit of all 12 screenshot pairs: 5 defects, 9 drift items
• Visual fixes (commits 5dfa175, 67c6372, bc2d3b1): hero H1 fix — real root cause was MDX wrapping multi-line JSX heading text in a docs <p> (leading-7 overriding h1 leading), fixed by inlining the text; Tailwind @source for gitignored content/docs (restored docs-only utility classes); copyPage:false on all marketing pages; credits page full-layout theme block; news image confirmed non-bug (lazy-load timing). Drift restorations per Matthieu: blue-tinted code blocks, "Search docs" placeholder; all other v4 look changes accepted (content width, green callouts, ↗ links, sidebar pill)
• Full-bleed marketing pages (commit 834ae93): layout:'full' in v4 only drops the TOC column — the theme MDX wrapper still caps content at --nextra-content-width (90rem). Fix the Nextra way: resolve active layout via normalizePages in the catch-all route, tag full pages with data-full-layout, override the documented --nextra-content-width var to 100% + zero article padding on those pages only. Measured at 1920px: home/cloud heroes = 1920, navbar inner + docs unchanged at 1440
• Round-3 fixes (commits 37c1076, aae06d5): React console errors on /cloud (stop-color→stopColor, missing key in tiers map; sweep of 6 pages + 43 map sites found no others); white background everywhere via <Head backgroundColor={{light:'#fff'}}>; docs blues were Nextra's default primary (hue 212) injected by <Head> overriding globals.css — fixed with <Head color={{hue:202,saturation:80,lightness:57}}> = Bref #3AA9E9 (dead CSS-var override removed)
• Sidebar page+folder duplicates (commit 3ad5ecc): v4 no longer collapses X.mdx + sibling X/ into one link — 7 sections showed a duplicated nested child (setup, deploy, runtimes, case-studies, local-development, monitoring, use-cases/http). Fixed the v4 way: moved each to X/index.mdx with asIndexPage: true. Routes unchanged, all URLs 200, folder headers now clickable links, 94 pages
• Matthieu: visual review round 2 + merge decision on PR Migrate website to Nextra 4 #2132

Known gotchas

• Pin next@15, NOT 16 — Nextra 4.6.1 + Next 16 500s on every route (Layout children bug)
• Override zod to 4.3.0 — zod 4.4.x breaks nextra-theme-docs 4.6.1 safeParse
• theme.layout:'raw' removed in v4 → layout:'full' + sidebar/toc/breadcrumb/pagination:false
• layout:'full' does NOT make pages full-bleed — content stays capped at --nextra-content-width (90rem); override the var per-page (see full-bleed fix above)
• Home page title needs title:{absolute} in generateMetadata, else double "– Bref"
• Prefer per-fetch { next: { revalidate } } over route-level export const revalidate
• MDX v3 needs a blank line after imports, else acorn parse errors
• export function inside MDX breaks component resolution → extract to .jsx files
• MDX has no HTML comments — use {/* ... */}
• nextra-theme-docs v4 CSS uses Tailwind v4 @layer → requires Tailwind 4 + @tailwindcss/postcss
• _meta.js uses export default; separators are { type: 'separator' }
• primaryHue is gone → CSS var --nextra-primary-hue

Follow-up candidates (pre-existing, not migration scope)

• Some internal .mdx-suffixed links in docs 404 (already broken on live prod)
• link-checker crashes on a literal http://localhost:8000/ example URL in docs prose
• 22 Markdown images in docs/ have empty alt text (![](...)) — Next.js dev overlay flags them as a11y errors (dev-only, build unaffected); fix = write descriptive alts

[mnapoli]

Phase 0 audit — migration map

Full API-by-API map below. TL;DR: large but mostly mechanical; 3 structural rewrites dominate (App Router move, next-seo removal in ~44 files, theme.config → Layout props). URLs preserved if content/ mirrors the current page tree.

Top risks

1. Hash-fragment redirects (~30 entries with # in redirects.js) are handled client-side in _app.jsx — server never sees the hash. App Router has no _app; must reimplement as a 'use client' component in app/layout.jsx or they silently break. Port early.
2. Data-in-MDX: index.mdx + credits.mdx use getStaticProps + nextra/data useData — no v4 equivalent. Must become async Server Components calling src/github/* / src/aws/invocations.js directly.
3. next-seo has zero App Router support (~44 files). Docs MDX → frontmatter; marketing pages → generateMetadata. Wide but mechanical; do as its own sweep.
4. xray/changelog.mdx is a React page inside MDX (export default function + getStaticProps) → convert to app/xray/changelog/page.jsx. 404.mdx → app/not-found.jsx.
5. layout:'raw' marketing pages (home/cloud/support/sentry/xray) carry client interactivity (useState, usePlausible) → extract 'use client' components; verify raw layout in v4.

Confirmed easy: Tab→Tabs.Tab (~81) and Card→Cards.Card (~16) renames; nextra/components path unchanged; next.config redirects()/middleware router-agnostic; next-plausible + next-sitemap App-Router-compatible; 15 _meta.json → _meta.js (all current features supported).

Full migration map (tables, unknowns, URL risks)

Migration map — configuration & infrastructure

Current usage	File(s)	v4 equivalent	Effort	Confidence
withNextra({theme, themeConfig, defaultShowCopyCode})	next.config.js	nextra({ defaultShowCopyCode: true, ... }) — theme/themeConfig removed; contentDirBasePath optional. Wrap order with plausible preserved.	S	high
redirects() (.html + redirects.js, permanent)	next.config.js, redirects.js	Unchanged — redirects() in next.config is router-agnostic. Keep as-is.	S	high
rewrites() /docs/:path*.md → /api/md/:path*	next.config.js	Keep rewrite; retarget to a Route Handler app/api/md/[...slug]/route.js reading raw MDX from content/docs.	M	high
withPlausibleProxy()	next.config.js	Supported in App Router. Keep proxy wrapper; move <PlausibleProvider> into app/layout.jsx.	S	high
next-sitemap postbuild	next-sitemap.config.js, package.json	Works with App Router (postbuild crawls build output). But postbuild must now ALSO run Pagefind — chain them (next-sitemap && pagefind ...).	S	med
Tailwind v3 config (custom blue palette, Inter font var, @tailwindcss/forms, darkMode:'class')	tailwind.config.js, postcss.config.js	Tailwind v4: @tailwindcss/postcss in postcss; move theme/colors into @theme in CSS; nextra-theme-docs v4 CSS is Tailwind v4 and must be imported. Verify @tailwindcss/forms v4 compat (used by support/checkout forms).	M	med
styles/main.css global import in _app.jsx	src/pages/_app.jsx	Import in app/layout.jsx; add nextra-theme-docs v4 stylesheet import.	S	high
Inter font via next/font/google in _app	src/pages/_app.jsx	Same API in app/layout.jsx; apply inter.variable to <html>.	S	high
middleware content-negotiation (accept: text/markdown → /api/md/)	src/middleware.js	Middleware unchanged in App Router. Keep; ensure rewrite target still resolves.	S	high

Migration map — theme.config.jsx (every option)

theme.config option	v4 destination	Notes	Effort	Confidence
logo: <AnimatedLogo>	<Navbar logo={...}> in layout	AnimatedLogo is client (animation) — mark 'use client'.	S	high
docsRepositoryBase	<Layout docsRepositoryBase>	direct prop	S	high
project.link (GitHub)	<Navbar projectLink>	direct prop	S	high
chat.link + Slack icon	<Navbar chatLink chatIcon>	direct props	S	high
banner {key,text}	<Banner storageKey>...</Banner> from nextra/components in layout	key→storageKey	S	high
useNextSeoProps() titleTemplate (%s – Bref, home special-case)	Root metadata.title.template + per-page title via frontmatter/generateMetadata	The / vs /index hack disappears in App Router (home is content/index.mdx).	M	med
useNextSeoProps openGraph default image	Root metadata.openGraph.images	Move to layout metadata.	S	high
darkMode:false + nextThemes{forcedTheme:'light'}	<Layout nextThemes={{forcedTheme:'light',defaultTheme:'light'}}>	Verify prop name in v4 docs theme.	S	med
primaryHue:202	v4 uses CSS var --nextra-primary-hue (set in CSS)	Tailwind v4 theming, not a prop.	S	med
sidebar.defaultMenuCollapseLevel:1	<Layout sidebar={{defaultMenuCollapseLevel:1}}>	direct prop	S	high
head() favicons/meta + conditional <link rel=alternate text/markdown> for docs	app/layout.jsx <Head> (nextra/components) for static tags; generateMetadata in catch-all for the per-docs-page .md alternate + metadataBase	Static favicons/verification/twitter → layout metadata. Conditional alternate → catch-all generateMetadata.	M	med
footer {component: Footer, text}	<Footer> in layout wrapping custom Footer component	Footer.jsx reused.	S	high
search: <DocSearch appId indexName apiKey>	Remove — <Search> (Pagefind) in <Navbar>	Drop @docsearch/react,@docsearch/css; add pagefind devDep + postbuild.	M	high
components.h1 custom class override	mdx-components.js useMDXComponents({ h1 })	Extract to app/mdx-components.js (was inline JSX — fine).	S	high

Migration map — content, components, data fetching

Current usage	File(s)	v4 equivalent	Effort	Confidence
import {Callout,Tab,Tabs,Cards,Card,Steps} from 'nextra/components' (~50 MDX files)	all docs MDX	Import path unchanged (nextra/components) BUT Tab→Tabs.Tab, Card→Cards.Card. ~81 <Tab> + 16 <Card> occurrences to rename.	M	high
MDX imports need blank line after them	all MDX	MDX3/acorn: ensure blank line between last import and content (known gotcha).	S	high
NextSeo in doc MDX (description-only, ~35 files)	docs/**.mdx	Delete import + tag; put description (and any title) in YAML frontmatter → Nextra v4 exports it as metadata.	M	high
NextSeo w/ title+openGraph (cloud, sentry, xray, support, index)	src/pages/*.mdx	Frontmatter + generateMetadata/export const metadata for OG images/titles.	M	med
getStaticProps + ssg + useData() (nextra/data)	index.mdx, credits.mdx	No v4 equivalent. Convert dynamic bits to async Server Components that call the fetch fns directly (getBrefInvocations, getSponsors, getContributors) and import them into the MDX. revalidate → export const revalidate on route or fetch cache opts.	L	med
export default function ChangelogPage inside xray/changelog.mdx (getStaticProps + full React page + dangerouslySetInnerHTML)	src/pages/xray/changelog.mdx	This is a React page, not markdown. Convert to app/xray/changelog/page.jsx async Server Component. export default function in MDX breaks v4 resolution anyway.	M	med
404.mdx (export default function)	src/pages/404.mdx	app/not-found.jsx.	S	high
usePlausible() hook	src/pages/cloud.mdx	Client hook — extract interactive parts into a 'use client' component; MDX page body stays server.	M	med
useState in MDX (cloud, sentry, xray checkout flows)	cloud/sentry/xray.mdx	Extract stateful UI (SentryCheckout,XRayCheckout,pricing toggles) into 'use client' components (mostly already separate components).	M	med
GitHub data fns (octokit graphql / fetch, env tokens)	src/github/*.js, src/aws/invocations.js	Already server-only; call directly from Server Components. No change to the fns.	S	high
src/aws/invocations.js CloudWatch	index homepage	Wrap in async Server Component <Invocations>; needs AWS creds at build/ISR time (fallback already present).	S	high

Migration map — _meta.json (15 files)

_meta.json → _meta.js with export default. Files: src/pages/_meta.json, docs/_meta.json, and docs/{default,deploy,environment,laravel,local-development,monitoring,runtimes,setup,symfony,upgrading,use-cases,use-cases/http}/_meta.json, news/_meta.json.

Feature in current _meta	v4 handling	Confidence
{type:'separator', title} (docs/_meta)	Supported; same shape in _meta.js.	high
{type:'page', title} top-nav items (root _meta)	Supported.	high
display:'hidden' (index, news, credits, 404, sentry, xray)	Supported (display:'hidden').	high
theme:{layout:'raw'} (index, cloud, support, sentry, xray, 404)	Supported per-page theme.layout:'raw'. Verify raw still named same in v4 docs theme.	med
theme:{typesetting:'article'} (news)	Supported.	med
{title, href:'/sentry'} external-ish link entries	Supported (href).	high
plain string titles + "" (inherit)	Supported.	high
Must be server files, no 'use client'; Zod-validated	Keep pure objects.	high

URL-change risk list (redirects are a hard requirement)

Baseline: v4 content/ mapping mirroring src/pages/ preserves all public paths. Watch items:

• Homepage /: today src/pages/index.mdx with the / vs /index SSG quirk. In v4 → content/index.mdx = /. The useNextSeoProps /index special-case is obsolete; confirm no internal links point to /index. Low risk, verify.
• .html redirects (/docs/:path*.html, plus .html entries in redirects.js): stay in next.config redirects(). No change, but must be re-verified after move.
• Hash-fragment redirects in redirects.js (e.g. /docs/runtimes#bref-ping, ~30 entries with #): these are handled client-side in _app.jsx because the server never sees the hash. App Router has no _app. Must reimplement as a 'use client' redirect component mounted in app/layout.jsx (read usePathname+window.location.hash). If dropped, all anchor redirects silently break. HIGH risk.
• Custom top-level pages (/cloud, /support, /sentry, /xray, /news, /news/*, /credits, /xray/changelog, /xray/docs, /sentry/docs, /sentry/terms, /xray/terms): map to content/ or app/ routes preserving the exact path. Enumerate each; the checkout/docs/terms subpages are easy to miss. Med risk.
• /docs/*.md and text/markdown negotiation: crawler-facing; reproduce exactly or AI-crawler markdown 404s. Med risk.
• Trailing-slash / case behavior: App Router defaults may differ; keep trailingSlash behavior consistent to avoid dupe-URL redirects. Low-med.

Unknowns needing a spike

1. Data-in-MDX pattern (index + credits). Confirm the clean v4 idiom for a content/*.mdx page that needs server-fetched data. Spike: async Server Component imported into MDX calling getBrefInvocations/getSponsors, with revalidate. Validate ISR/revalidate still applies to a content/ MDX route. (Biggest correctness unknown.)
2. Per-page theme.layout:'raw' in v4 for the non-docs marketing pages (home/cloud/support/sentry/xray). Confirm raw layout exists and renders full-width without docs chrome; else those pages need app/ routes outside the docs <Layout>. Spike one page.
3. Pagefind + next-sitemap postbuild chaining and Pagefind indexing of a mixed docs+marketing site (does it index layout:raw pages? do we want it to?). Confirm output path/CSP and that search only surfaces docs.
4. .md route handler from content/: confirm reading raw MDX + stripping imports/NextSeo still works when source is content/docs (and NextSeo will be gone → simplify the stripper).
5. Tailwind v4 + @tailwindcss/forms + nextra-theme-docs v4 CSS coexistence; custom blue palette + primaryHue via @theme; forcedTheme:'light' interaction with v4 dark styles.
6. generateMetadata title template + OG per page replicating useNextSeoProps behavior across docs vs marketing pages.

Recommended migration-order adjustments

Issue #2130's order is sound; suggested refinements:

1. Do a data-fetching spike (unknown Event body parsing issue #1) before bulk content move — it dictates the pattern for index/credits/changelog and de-risks the largest item.
2. Scaffold app/layout.jsx + mdx-components.js + one catch-all docs route first, get ONE docs page rendering with v4 theme, then bulk-move content. Validates theme.config→props mapping early.
3. Treat next-seo removal as its own sweep (44 files, mechanical) separate from the Tab→Tabs.Tab rename sweep — both are wide but low-risk; batch each.
4. Port the client hash-redirect logic early into app/layout.jsx (URL requirement, easy to forget, HIGH risk).
5. Marketing/checkout pages (cloud,sentry,xray,support,changelog) after docs — they carry the client-component (useState/usePlausible) and layout:raw complexity; keep them off the critical path.
6. aws-cdk.mdx RemoteContent removed in separate prep PR — excluded here.

Sources

• Nextra v4 migration guide
• next-plausible App Router
• next-sitemap App Router

[mnapoli]

Phase 1 spike — all 6 unknowns answered (working next build)

Spike scaffold lives on branch worktree-agent-a61252823a9d0f300 under website/spike/ (self-contained). Load-bearing commit: 5ce77963. Repro: cd website/spike && npm install && npm run build.

Verdicts

1. Data-in-MDX: async Server Component imported into MDX, calling the fetch fn directly. Proven with real build-time fetches (home invocations counter, credits sponsors/contributors). ISR: prefer per-datasource fetch(..., { next: { revalidate } }) over route-level export const revalidate (coarse, all routes).
2. layout:'raw' is REMOVED in v4 → theme: { layout: 'full', sidebar: false, toc: false, breadcrumb: false, pagination: false, timestamp: false }. Verified chrome-free rendering; no standalone app/ routes needed for marketing pages.
3. Pagefind: postbuild: next-sitemap && pagefind --site .next/server/app works. Caveat: marketing pages ARE indexed by default — docs-only search needs explicit exclusion (small task).
4. .md handler: route handler reading content/docs, strip imports + frontmatter (NextSeo regex no longer needed) → 200 text/markdown. Middleware content negotiation composes unchanged.
5. Tailwind v4: postcss plugin + @plugin forms + nextra CSS + blue palette in @theme + --nextra-primary-hue: 202deg + forcedTheme:'light' all coexist. tailwind.config.js becomes ~empty.
6. Metadata: root title.template '%s – Bref' + catch-all generateMetadata from frontmatter; description/OG/twitter/alternate-.md all verified in built HTML. Gotcha: home needs title: { absolute } or you get a double "– Bref".

⚠️ Two build-blockers not in the Phase 0 audit

• Pin Next 15, not 16: Nextra 4.6.1 + Next 16 → every route 500s at prerender (Layout children bug).
• Override zod to 4.3.0: zod 4.4.x breaks nextra-theme-docs 4.6.1's Layout.safeParse (latent theme bug).

Working stack: next@15.5, react@19.2, nextra@4.6.1, nextra-theme-docs@4.6.1, zod@4.3.0 (override), tailwindcss@4, @tailwindcss/forms@0.5, pagefind@1.5, next-sitemap@4.

In-place vs fresh: FRESH scaffold + port content. The v2→v4 delta is a hard architectural cut — the scaffold doesn't survive (theme.config, _app, getStaticProps, next-seo, tailwind.config all deleted); what survives (MDX bodies, fetch fns, Footer/Logo components, redirects.js) is copied, not migrated. Fresh stays buildable from commit 1 and keeps master deployable; the spike is already ~90% of the skeleton. Effort update: data pages drop from L to S–M (pattern proven); new small task: Pagefind docs-only exclusion.

[mnapoli]

Phase E verification — READY FOR REVIEW, zero regressions vs production

Check	Result
Sitemap URL sweep (local build vs live)	91/91 pass
redirects.js (67 entries) + .html pattern	71/72 (1 fail: pre-existing on prod, now fixed)
/docs/*.md crawler endpoints	66/70 (4 fails: all pre-existing on prod, now fixed)
Browser: hash redirects, docs-only search, calculator/pricing/tabs	5/5 pass
Screenshots	24 prod-vs-new pairs captured for visual review

Independent code review of the branch: 0 high-severity findings. 6 low-severity fixes applied in e4acf3f (the only true regression — a broken .md alternate link on /docs — plus path-traversal hardening and 4 improvements over prod behavior: .md-source pages and /docs.md now serve markdown, dead /docs/web-apps* redirects revived, 41 unmatchable hash entries removed from server redirects).

Remaining step: maintainer visual review + merge decision on #2132.