Migrate from Nextra
Nextra and the Farming Labs Next.js adapter both use Next.js and MDX, making this one of the most
direct migrations. Most effort goes into replacing Nextra route/layout wiring, _meta navigation,
and theme-specific components.
Keep the Next.js application
When the existing Next.js application should remain, initialize Farming Labs Docs inside it and migrate only the docs surface. You do not need to recreate the entire app.
1. Inventory the source
Locate:
content/orsrc/content/pages/MDX contentapp/**/page.mdxcontent_meta.js,_meta.ts,_meta.jsx,_meta.tsx, or_meta.global.*next.config.*and thenextra(...)wrappertheme.config.*,mdx-components.*, and layout files- custom React components, CSS, and
public/ - search, i18n, redirects, and custom Next.js middleware
2. Choose the target shape
For the shortest migration, keep Next.js and use the Farming Labs Next.js adapter:
| Nextra | Farming Labs Next.js |
|---|---|
content/foo.mdx | app/docs/foo/page.mdx |
app/foo/page.mdx | app/docs/foo/page.mdx, adjusted for the chosen docs base |
_meta.* | File hierarchy and order frontmatter |
| Nextra catch-all page | Generated Farming Labs docs route |
theme.config.* | docs.config.ts theme, navigation, and page actions |
mdx-components.* | docs.config.ts components registry |
public/** | Existing public/** |
If you are also changing runtime, move the MDX into that adapter's configured contentDir after
first making the content portable.
3. Convert _meta navigation
Nextra _meta files can define order, titles, hidden items, separators, external links, and navbar
pages. For each directory:
- Preserve the object key order.
- Rename or position the matching page.
- Add numeric
orderfrontmatter. - Use the configured title as page
titlewhen appropriate. - Move
display: "hidden"pages outside normal navigation or use supported hidden behavior. - Recreate separators and external links with folder structure or custom sidebar/navigation.
JSX labels and functions inside _meta are application code. Replace them with stable text and
registered icons instead of trying to serialize them into frontmatter.
4. Preserve content and routes
Keep portable frontmatter such as title, description, and date fields. Review Nextra-specific
fields including asIndexPage, type, display, theme overrides, and layout flags.
When moving from content/foo.mdx to Next.js, the destination is normally:
app/docs/foo/page.mdxUse a folder page.mdx for section landing pages. Compare the final route with the source before
moving on.
5. Convert components
| Nextra pattern | Target |
|---|---|
Nextra <Callout> | Farming Labs <Callout> |
Nextra <Tabs> | Built-in <Tabs> and <Tab> |
nextra/components imports | Built-in or registered local components |
useConfig() | Static frontmatter or target runtime data |
Nextra Cards | Built-in cards or a local registered component |
custom mdx-components mapping | docs.config.ts components |
Component names can match while props differ. Remove Nextra imports only after translating their uses and verifying the page.
6. Replace framework wiring
After the migrated docs route builds:
- remove the Nextra wrapper from
next.config.* - remove the Nextra catch-all route if it overlaps
- replace Nextra layout and theme configuration
- keep unrelated Next.js routes, middleware, fonts, and application providers
- remove Nextra dependencies only after no imports remain
This order keeps the migration reversible and avoids breaking non-doc pages.
7. Validate and recover
- Run the Next.js production build.
- Compare the Nextra page map with the Farming Labs sidebar.
- Test index pages, hidden pages, external links, imported components, and images.
- Verify application routes outside
/docs. - Fetch migrated pages with
.md. - Remove Nextra dependencies only after all checks pass.
If a route is duplicated, disable one catch-all and retry. If navigation differs, return to the
nearest _meta file and translate its key order and special item types explicitly.
Source references
Migrate Nextra content, _meta navigation, layouts, and MDX components to Farming Labs Docs
How is this guide?