unstale

npm / nextra

nextra

What changed in nextra 3 to 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-23.

101 breaking37 new APIs and options2 performance13 behavior and defaults2 tooling1 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.4 on npm

nextra 4101 changes

Breaking changes 62

  • Nextra 4 exclusively uses the Next.js App Router; Pages Router support has been discontinued.

    4.0.0upgrade guide

  • Nextra 4 uses Next.js App Router and discontinues Pages Router support.

    4.0.0upgrade guideupgrade guide

  • collectCatchAllRoutes is removed.

    4.0.0upgrade guide

  • The color-primary-750 theme color variant is removed.

    4.0.0upgrade guide

  • compileMdx now returns Promise<string> instead of Promise<object>.

    4.0.0upgrade guideupgrade guide

  • contentDirBasePath replaces useContentDir and configures the content directory under a catch-all subdirectory.

    4.0.0upgrade guide

  • convertPageMapToJs is now synchronous.

    4.0.0upgrade guide

  • createCatchAllMeta is removed from nextra/catch-all.

    4.0.0upgrade guide

  • Use display: 'hidden' in a blog _meta file instead of the draft: true front matter option.

    4.0.0upgrade guide

  • External links in MDX now open in a new tab with rel="noreferrer" and a visual ↗ suffix icon.

    4.0.0upgrade guide

  • getPageMap now accepts one optional root argument instead of lang and route arguments.

    4.0.0upgrade guide

  • The Head component moves to nextra/components.

    4.0.0upgrade guide

  • mdx-components replaces nextraConfig.mdxOptions.providerImportSource for adding or overriding code-block icons.

    4.0.0upgrade guide

  • The server component is named <MDXRemote>; it was previously called <RemoteContent>.

    4.0.0upgrade guide

  • Use MDXRemote from nextra/mdx-remote; its default components are provided automatically from mdx-components.jsx.

    4.0.0upgrade guide

  • These files must be server components without a 'use client' directive; zod parses and transforms them on the server.

    4.0.0upgrade guide

  • External links declared in _meta files open in a new tab, use rel="noreferrer", and display a ↗ suffix icon.

    4.0.0upgrade guide

  • Front matter fields are exported as an MDX metadata object; MDX files may instead export metadata directly, but cannot use both approaches.

    4.0.0upgrade guide

  • TypeScript projects should set moduleResolution to bundler instead of node to avoid type errors.

    4.0.0upgrade guide

  • The _meta newWindow field was removed.

    4.0.0upgrade guideupgrade guide

  • Use the Next.js Metadata API instead of the head theme config option for dynamic head tags.

    4.0.0upgrade guide

  • Nextra 4 requires Next.js 14 or later.

    4.0.0upgrade guideupgrade guide

  • Several components, including <Collapse>, <Details>, <Summary>, <Select>, and <Head>, moved from nextra-theme-docs to nextra/components for use in custom themes.

    4.0.0upgrade guide

  • Components including Collapse, Details, Summary, SkipNavContent, SkipNavLink, Select, and Bleed move from nextra-theme-docs to nextra/components.

    4.0.0upgrade guide

  • The nextra/context entry point is removed.

    4.0.0upgrade guide

  • The nextra/mdx entry point is renamed to nextra/mdx-components.

    4.0.0upgrade guide

  • The nextra/remark-plugins entry point is removed.

    4.0.0upgrade guide

  • The nextra/remote entry point is removed.

    4.0.0upgrade guide

  • The nextra/schemas entry point is removed.

    4.0.0upgrade guide

  • NextraConfig.transformPageMap is removed.

    4.0.0upgrade guide

  • The NextraThemeLayoutProps type is removed.

    4.0.0upgrade guide

  • normalizePageRoute is removed.

    4.0.0upgrade guide

  • Search migrated from FlexSearch to Pagefind, which indexes remote MDX, dynamic Markdown/MDX content, imported files, and static pages.

    4.0.0upgrade guideupgrade guiderelease notes

  • Install Pagefind as a dev dependency and run it after building to index generated HTML pages.

    4.0.0upgrade guide

  • Remote docs setups need a modified pageMap list in the layout file for sidebar navigation links to display correctly.

    4.0.0upgrade guide

  • The optional peer dependency was removed; the theme uses the Cusdis SDK directly in its <Comments> component.

    4.0.0upgrade guide

  • RemoteContent was renamed to MDXRemote and moved from nextra/components to nextra/mdx-remote.

    4.0.0upgrade guideupgrade guide

  • renderComponent is removed.

    4.0.0upgrade guide

  • renderString is removed.

    4.0.0upgrade guide

  • Sidebar titles now fall back to the first Markdown h1 heading after checking _meta, sidebarTitle, and title front matter.

    4.0.0upgrade guide

  • Theme stylesheets are no longer imported by themes; import the appropriate theme style.css manually.

    4.0.0upgrade guide

  • Th, Tr, and Td are now accessed as Table.Th, Table.Tr, and Table.Td instead of separate imports.

    4.0.0upgrade guide

  • The standalone Td export was removed; use Table.Td.

    4.0.0upgrade guideupgrade guide

  • The standalone Th export was removed; use Table.Th.

    4.0.0upgrade guideupgrade guide

  • The theme option was removed from Nextra configuration.

    4.0.0upgrade guide

  • The theme.bottomContent field was removed.

    4.0.0upgrade guide

  • Nextra 4 no longer supports theme.config files for configuring theme options.

    4.0.0upgrade guide

  • The components theme config option was removed; provide custom components inside useMDXComponents instead.

    4.0.0upgrade guide

  • The direction theme config option was removed; set the dir attribute on the <html> tag.

    4.0.0upgrade guide

  • The feedback.useLink theme config option was removed.

    4.0.0upgrade guide

  • The head theme config option was removed; use <Head> or the Next.js Metadata API.

    4.0.0upgrade guide

  • The main theme config option was removed.

    4.0.0upgrade guide

  • The themeSwitch.component theme config option was removed.

    4.0.0upgrade guide

  • The toc.component theme config option was removed.

    4.0.0upgrade guide

  • The theme.layout: 'raw' option was removed; use page.{jsx,tsx} files to create pages without a layout.

    4.0.0upgrade guide

  • The theme.topContent field was removed.

    4.0.0upgrade guide

  • The themeConfig option was removed from Nextra configuration.

    4.0.0upgrade guide

  • Generated MDX pages no longer export const title.

    4.0.0upgrade guide

  • The exported TOC value is now toc instead of useTOC.

    4.0.0upgrade guide

  • The standalone Tr export was removed; use Table.Tr.

    4.0.0upgrade guideupgrade guide

  • Nextra’s useRouter hook was removed; use useRouter from next/navigation instead.

    4.0.0upgrade guide

  • The theme’s Tailwind CSS class prefix changed from _ to x:; update overridden theme classes accordingly.

    4.0.0upgrade guideupgrade guide

New APIs and options 27

  • Nextra 4 supports the App Router.

    4.0.0release notes

  • Set asIndexPage: true in front matter to make a page serve as the index for its folder.

    4.0.0upgrade guide

  • Set the path from which content is served when using the Content Directory Convention.

    4.0.0upgrade guide

  • Create a rendered listing of a route’s subpages, using getPageMap to supply the page map.

    4.0.0upgrade guide

  • Mark the main content area of JavaScript or TypeScript pages to have its content indexed by Pagefind.

    4.0.0upgrade guide

  • Add this attribute to tags whose content should be excluded from Pagefind indexing.

    4.0.0upgrade guide

  • Get a route’s page map for use with createIndexPage to list its subpages.

    4.0.0upgrade guide

  • The docs and blog themes support rendering GitHub alert syntax in Markdown and MDX as Callout components.

    4.0.0upgrade guiderelease notes

  • Set the optional icon front matter field on a subpage to show an icon on its card.

    4.0.0upgrade guide

  • Add an app layout file to configure the Nextra layout, theme components, metadata, and page map.

    4.0.0upgrade guide

  • Create this root-level file to define global MDX components.

    4.0.0upgrade guide

  • mergeMetaWithPageMap is added to nextra/page-map.

    4.0.0upgrade guide

  • Define pages across folders in one suffixed _meta file; folder items must include an items field.

    4.0.0upgrade guide

  • A root _meta.global file is added; supported extensions include js, jsx, ts, and tsx.

    4.0.0upgrade guide

  • Nextra 4 introduces the _meta.global file.

    4.0.0release notes

  • Add --turbopack to the dev command to use Nextra with Turbopack.

    4.0.0upgrade guideupgrade guide

  • The blog theme adds support for the View Transitions API using this package.

    4.0.0upgrade guide

  • normalizePagesResult gains activeMetadata to retrieve front matter or metadata exported from a page.

    4.0.0upgrade guide

  • The Page File Convention uses the Next.js App Router convention with enhanced page extensions for MD and MDX files.

    4.0.0upgrade guide

  • A Rust-powered search engine provides faster performance and better search results.

    4.0.0upgrade guide

  • The Search component is exported from nextra/components for use in custom themes; the blog theme also supports search.

    4.0.0upgrade guide

  • The blog theme supports built-in search; import <Search> from nextra/components and place it inside <Navbar>.

    4.0.0upgrade guide

  • Nextra 4 adds support for Server/Client components.

    4.0.0release notes

  • Translations can be dynamically loaded in server components and passed as props to theme components, avoiding shipping client translation dictionary files.

    4.0.0upgrade guide

  • Whitelist HTML elements to be replaced with components from mdx-components.js; by default only <details> and <summary> are replaced.

    4.0.0upgrade guideupgrade guide

  • Wrap the Pre component with custom icons for specified code languages.

    4.0.0upgrade guide

  • Wrapper gains a bottomContent prop for placing content after pagination in nextra-theme-docs.

    4.0.0upgrade guide

Performance 2

  • The Docs Example's shared First Load JS decreased by 36.9%, from 168 kB to 106 kB.

    4.0.0upgrade guiderelease notes

  • Imports from nextra/components, nextra-theme-docs, and nextra-theme-blog are optimized internally with Next.js optimizePackageImports to improve bundle size.

    4.0.0upgrade guide

Behavior and default changes 7

  • JSX and TSX code blocks now display the React icon; diff blocks with a filename use the icon for that file extension.

    4.0.0upgrade guide

  • The built-in 404 page includes an issue-creation URL with the referrer URL to help identify broken links.

    4.0.0upgrade guide

  • Page collection now includes static jsx and tsx pages from the app directory, as well as static md and mdx pages.

    4.0.0upgrade guide

  • Built-in internationalization capabilities now support React Server Components.

    4.0.0upgrade guiderelease notes

  • The primary color variant set through the Head component’s color prop is now used for text selection styles.

    4.0.0upgrade guide

  • The table of contents can show React components, interpolated variables, and LaTeX, including for remote content.

    3.0.0, 4.0.0release notesupgrade guide

  • Headings now animate when in the :target state.

    4.0.0upgrade guide

Tooling 2

Fixes and other changes 1

nextra 355 changes

Breaking changes 39

  • The _app.mdx convention is removed; use _app.{js,jsx} or _app.{ts,tsx} for TypeScript projects instead.

    3.0.0release notes

  • The standalone Card export is removed; use Cards.Card instead.

    3.0.0release notes

  • The image prop is removed; image display is determined by the truthiness of children.

    3.0.0release notes

  • The minimum supported Node.js version is 18.

    3.0.0release notes

  • Nextra bundles to ESM only; use next.config.mjs or next.config.js with type: module.

    3.0.0release notes

  • Support for frontMatter.mdxOptions is removed.

    3.0.0release notes

  • layout.tsx is removed; move directly to setup-page.tsx.

    3.0.0release notes

  • defaultLocale is removed from LoaderOptions.

    3.0.0release notes

  • Importing MD or MDX files outside the working directory is disallowed; use symlinks instead.

    3.0.0release notes

  • Nextra updates to MDX3.

    3.0.0release notes

  • Support for _meta.json is removed; use _meta.{js,jsx,ts,tsx} instead.

    3.0.0release notes

  • The package declares type: module and is bundled to ESM only; use next.config.mjs or next.config.js with type: module.

    3.0.0release notes

  • The nextra/filter-route-locale export is removed.

    3.0.0release notes

  • The route-specific themeConfig internal context field is removed.

    3.0.0release notes

  • The Nextra middleware export is removed.

    3.0.0release notes

  • The nextra/mdx-plugins export is removed; nextra/remark-plugins is added.

    3.0.0release notes

  • resolvePageMap moves to nextra/page-map-dynamic.

    3.0.0release notes

  • Adds the nextra/remove-links export.

    3.0.0release notes

  • The nextraConfig.flexsearch option is renamed to nextraConfig.search.

    3.0.0release notes

  • The hot page option is removed.

    3.0.0release notes

  • The pageNextRoute page option is removed.

    3.0.0release notes

  • The pageOptsChecksum page option is removed.

    3.0.0release notes

  • locale and defaultLocale are removed from normalizePages.

    3.0.0release notes

  • The Tailwind prefix changes from nx- to _ to reduce bundle size.

    3.0.0release notes

  • pageMapCache is removed from nextra/page-map.

    3.0.0release notes

  • pageOpts.headings is renamed to toc.

    3.0.0release notes

  • The pageOpts.newNextLinkBehavior field is removed.

    3.0.0release notes

  • The pageOpts.route field is removed.

    3.0.0release notes

  • Remove PageOpts.toc; use the toc prop from components.wrapper.

    3.0.0release notes

  • parseFileName is removed from nextra/utils.

    3.0.0release notes

  • The Next.js peer dependency requirement is set to >=13.

    3.0.0release notes

  • React 18 becomes the minimum requirement.

    3.0.0release notes

  • RemoteContent moves from nextra/data to nextra/components.

    3.0.0release notes

  • resolvePageMap is removed from nextra/page-map.

    3.0.0release notes

  • Nextra switches to shikiji instead of shiki for syntax highlighting.

    3.0.0release notes

  • The standalone Tab export is removed; use Tabs.Tab instead.

    3.0.0release notes

  • The Nextra option transformPageOpts is replaced by transformPageMap.

    3.0.0release notes

  • useData moves from nextra/data to nextra/hooks.

    3.0.0release notes

  • useSSG is renamed to useData.

    3.0.0release notes

New APIs and options 10

  • Adds a Nextra configuration option to import official theme CSS into a specific cascade layer.

    3.0.0release notes

  • Front matter can set the page label shown in the sidebar.

    3.0.0release notes

  • Adds MathJax support.

    3.0.0release notes

  • Adds support for JavaScript and TypeScript _meta files, including JSX.

    3.0.0release notes

  • Adds the nextra/fetch-filepaths-from-github export.

    3.0.0release notes

  • Adds useRouter for fetching locale and defaultLocale.

    3.0.0release notes

  • recmaPlugins can be passed in mdxOptions.

    3.0.0release notes

  • Adds remark-smartypants support.

    3.0.0release notes

  • Adds shikiji twoslash support.

    3.0.0release notes

  • Code block metadata can set word-wrap=false to disallow the mobile word-wrap button.

    3.0.0release notes

Behavior and default changes 6

  • The icon prop becomes optional.

    3.0.0release notes

  • Front matter is inserted as an export node via a custom remark plugin.

    3.0.0release notes

  • Nextra configuration gains Zod validation.

    3.0.0release notes

  • Repeated imports of the same image are deduplicated, and images can be imported through Markdown image definitions.

    3.0.0release notes

  • className uses render props with selected, disabled, and hover state.

    3.0.0release notes

  • The Tab component is crawlable and indexable by search engines by default.

    3.0.0release notes