Nextra 3

[dimaMachina]

below of my thoughts on the next biggest release

• allow only ESM config next.config.mjs or next.config.js with "type": "module" [v3] bundle to ESM only, use next.config.mjs or next.config.js with "type": "module" #2254

the whole nextra should be bundled to ESM only instead of mixing cjs and esm

also this should fix blocked renovate PRs #1136 #1083 which one now ESM only

• implement new i18n proposal A directory instead of an extension at I18N. #176 [wip v3]: new i18n, remove _app.mdx, remove newNextLinkBehavior #2070

• add support for _meta.{js,jsx,ts,tsx} with JSX support Proposal: replace _meta.json in favor of _meta.{js,jsx,ts,tsx} #852 [V3] experiment with _meta.{js,jsx,ts,tsx} #2272

this should fix the following #1263 and avoid future bugs with redirects of #1354 #1402

• official versioning support + new docs on how to setup it Versioned docs #20

• set by default loaderOptions.defaultShowCopyCode to true and in compileMdx also

• nextra-theme-docs

  • set by default sidebar.toggleButton to true some major updates #2248
  • made a renames of theme configs for nextra-theme-docs Rename configurations #826 [v3/docs] rename theme config options #2258
  • remove newNextLinkBehavior option and in nextra loader also [wip v3]: new i18n, remove _app.mdx, remove newNextLinkBehavior #2070
  • remove custom <Anchor /> component and use plain NextLink everywhere
  • Componentize the docs theme #332
  • remove Steps, Callout, Tabs, Cards, FileTree exports some major updates #2248

• nextra-theme-blog

  • use NextLink without legacyBehavior prop [v3] blog changes #2252
  • validate theme config options with zod?
  • remove config.cusdis. Pass cusdis options as props in Cusdis component [v3] blog changes #2252

• set next 13 as minimal supported version [v3] set "peerDependencies.next": ">=13" #2249

• rename nextra/ssg to nextra/data [v3] more major updates #2251

• remove the current workaround to allow import MDX outside of CWD and add console.error if there are such as cases import mdx from parent directory cause Hydration fail #1424 (comment) [v3] more major updates #2251

• prefer to use _app.tsx/jsx over _app.mdx Feedback: using _app.mdx vs _app.tsx is weird and more error prone #1632 (comment) [wip v3]: new i18n, remove _app.mdx, remove newNextLinkBehavior #2070

• Remove Tab in favour Tabs.Tab, remove Card in favour Cards.Card [v3] more major updates #2251

• update remark-math to v6 TypeError: Cannot read properties of undefined (reading 'mathFlowInside') #2368
  tbd

[juliusmarminge]

You got a rough timeline for this release?

[dimaMachina]

@juliusmarminge nope

[pomber]

any plans for experimental support for React Server Components? or you'll wait for a stable app directory?

[dimaMachina]

no plans currently

[ecraig12345]

Whatever features you include, please try to document the breaking changes better. Migrating a simple site from 1 to 2 was a big headache due to the lack of documentation about renamed settings and other changes.

[dimaMachina]

Whatever features you include, please try to document the breaking changes better. Migrating a simple site from 1 to 2 was a big headache due to the lack of documentation about renamed settings and other changes.

Which renamed settings were not documented and other changes?

[ecraig12345]

Whatever features you include, please try to document the breaking changes better. Migrating a simple site from 1 to 2 was a big headache due to the lack of documentation about renamed settings and other changes.

Which renamed settings were not documented and other changes?

This discussion was the only migration/upgrade guide I could find. It doesn't mention any of the renamed settings (specifically for nextra-theme-docs config in my case), and it's not linked from the changelog or anywhere else that I saw (I found it with search).

Looking again at the nextra-theme-docs changelog, I now see there is an entry for "various theme config options was renamed" (under "patch" which is incorrect for a breaking change), but just linking out to a code file which doesn't mention the old names is not very helpful. There were also some settings like the search and footer where the expected type changed from boolean to object.

The other break I noticed was an nx- prefix was added to class names (some of the code in the site I was upgrading used those), though I'm not sure if those were intended for public use.

The simplest way to make future upgrades easier for your users is to make sure that any breaking changes have a changeset with type "major" (with a detailed description of any breaks) so that they end up in the "Major changes" section of the changelog--that would probably have been enough to help me. But it also doesn't hurt to have a separate upgrade/migration guide, sort of like these ones for Next.js, ESLint, or Fluent UI React (those are much larger tools/libraries, but it shows the general idea).

It might also be worth more explicitly calling out that there were styling changes, with before/after screenshots of a demo site so people can see how their site will change (though this isn't quite as important, since it's automatic and people can see it in local testing). The parts of the v2 styling changes that confused me were the footer moving from the bottom of the main column to the bottom of the page, and the edit link moving from the footer to the right sidebar. When testing, I thought the edit link had disappeared or maybe I was missing a setting to make it show up--but it turns out this was just because my window width was under 1280px (laptop screen with vertical tabs) and the right sidebar isn't shown at that width. A before/after screenshot would have clarified that the link had moved and my screen was too small to see it.

[dimaMachina]

#257 was the only migration/upgrade guide I could find. It doesn't mention any of the renamed settings (specifically for nextra-theme-docs config in my case), and it's not linked from the changelog or anywhere else that I saw (I found it with search).

For theme config options just look at docs page https://nextra.site/docs/docs-theme/theme-configuration
Also, I made setup zod validation of theme config options to avoid typos, also you can use theme.config.tsx file and import DocsThemeConfig type

Looking again at the nextra-theme-docs changelog, I now see there is an entry for "various theme config options was renamed" (under "patch" which is incorrect for a breaking change), but just linking out to a code file which doesn't mention the old names is not very helpful. There were also some settings like the search and footer where the expected type changed from boolean to object.

Not a big deal, the most important thing is that it was released as Major release

The other break I noticed was an nx- prefix was added to class names (some of the code in the site I was upgrading used those), though I'm not sure if those were intended for public use.

it was made to avoid conflicts with the user's tailwind config

The simplest way to make future upgrades easier for your users is to make sure that any breaking changes have a changeset with type "major" (with a detailed description of any breaks) so that they end up in the "Major changes" section of the changelog--that would probably have been enough to help me.

we already use changesets, we had 100 alpha releases and we can't catch everything

But it also doesn't hurt to have a separate upgrade/migration guide, sort of like these ones for Next.js, ESLint, or Fluent UI React (those are much larger tools/libraries, but it shows the general idea).

Unfortunately, Nextra is not a such popular as your mentioned repository where there are 5-10 maintainers and a LOT of contributors, we try to improve it as we can

It might also be worth more explicitly calling out that there were styling changes, with before/after screenshots of a demo site so people can see how their site will change (though this isn't quite as important, since it's automatic and people can see it in local testing). The parts of the v2 styling changes that confused me were the footer moving from the bottom of the main column to the bottom of the page, and the edit link moving from the footer to the right sidebar. When testing, I thought the edit link had disappeared or maybe I was missing a setting to make it show up--but it turns out this was just because my window width was under 1280px (laptop screen with vertical tabs) and the right sidebar isn't shown at that width. A before/after screenshot would have clarified that the link had moved and my screen was too small to see it.

As I mentioned I can't cover everything just feel free to contribute, @shuding already wrote amazing docs for Nextra v2

[dacevedo12]

Any chance of supporting turbopack in the next major or will nextra wait for a stable release?

#1054

[dimaMachina]

@dacevedo12 no chances, pr welcome

[chakhsu]

Thank you very much for this project and I can't wait to use the Nextra 3. https://grpcity.vercel.app/ is the use of the Nextra 3 online example, running very well, thanks again.

[abenhamdine]

Thank you very much for this project and I can't wait to use the Nextra 3. https://grpcity.vercel.app/ is the use of the Nextra 3 online example, running very well, thanks again.

I see that this site has been built with v3 branch https://github.com/chakhsu/grpcity-docs/blob/56e95759c2510d9103892e81dd6e28aeeba54eba/package.json#L21
Did you encounter any bug/gotcha ?

[chakhsu]

Thank you very much for this project and I can't wait to use the Nextra 3. https://grpcity.vercel.app/ is the use of the Nextra 3 online example, running very well, thanks again.

I see that this site has been built with v3 branch https://github.com/chakhsu/grpcity-docs/blob/56e95759c2510d9103892e81dd6e28aeeba54eba/package.json#L21 Did you encounter any bug/gotcha ?

I didn't encounter a bug. I just make sure that the configuration and usage are the same as in the v3 example.

[dimaMachina]

For anyone wants to try Nextra 3 here is my blog post with all the features and a migration guide from Nextra 2

https://the-guild.dev/blog/nextra-3

[SaadBazaz]

Been waiting for Nextra 3 for too long <3

However, would really really need appDir support. Bumping up to >= Next 13 does not make sense if we can't use the new router; we're pretty much stuck at Next 13 because 14 doesn't even have the pages dir.

Need this in appDir because I want to build a hybrid site which can have both docs and SaaS. Less maintenance, single repo, shared providers... that's the sweet deal.

[abenhamdine]

However, would really really need appDir support. Bumping up to >= Next 13 does not make sense if we can't use the new router; we're pretty much stuck at Next 13 because 14 doesn't even have the pages dir.

I disagree it does not make sense, pages router is going nowhere and will probably be supported several years by Next.js, given the huge amount of websites using it.

Need this in appDir because I want to build a hybrid site which can have both docs and SaaS. Less maintenance, single repo, shared providers... that's the sweet deal.

You can just set two different folders (a la monorepo).
For example, we have our SaaS in folder /client and the docs in folder /docs
They are different apps, each with its package.json file.

[SaadBazaz]

I'm more of a monolith guy :p
I was thinking of having tight knit integration between my docs, and SaaS. That's why was preferring to have just App Router.

app
|_ (docs)
|_ (saas-tool)
|_ layout.tsx

I thought Next was deprecating pages as they moved forward? It's still in the air and I wouldn't risk being on an old architecture for such an awesome library like Nextra which, honestly, has great potential to be the go-to static site maker.

++ Another reason why monolith is so I can get the sweet-sweet routes:
https://myapp.com/docs -> Nextra
https://myapp.com -> SaaS tool
Without having to manage a reverse proxy or anything of the sort.

[SaadBazaz]

I think from here onwards, given all the effort put in by the awesome @dimaMachina , a good way forward is:

1. Make a shittonne of good templates for Nextra 3,
2. Separate the Nextra Components library and give devs easy access to add more components (Maybe using shadcn/ui or Radix as a base design system would help in that), add components like Editor.js built-in
3. Put in major effort in appDir migration, and try to make Nextra part of Nextjs mainstream

[dimaMachina]

⚠️ Nextra 3 will not have support for the app router, please move all discussions and ideas related to the app router in according pinned issue #2023

[hariria]

@dimaMachina any ETA on when we will be able to try this out? Would rather use Nextra 3 than 2 if it's coming out soon. Looks great btw (https://the-guild.dev/blog/nextra-3)

[dimaMachina]

@hariria you can already try v3 alpha version, there is no date when it will be released since I maintain this framework alone

[maciejkwas]

@SaadBazaz were you successful on getting your setup right? I need exactly same structure but with i18n support, would you like to collab to get some PR maybe on that?

[dimaMachina]

@maciejkwas https://github.com/shuding/nextra/tree/v3/examples/swr-site here is working i18n example

[Genesis3800]

Hey @dimaMachina lots of love and regards to you for what you've built.
Really excited for Nextra 3.
Do you have a rough timeline right now for when it might be ready for stable release?

[dimaMachina]

Hey @dimaMachina lots of love and regards to you for what you've built. Really excited for Nextra 3. Do you have a rough timeline right now for when it might be ready for stable release?

Thank you 🙌.
The stable release will be released once I will polish own Nextra 3 docs to include new changes, I can't say when it will be done.
Also, I already started work on Nextra 4 with app router support, so more amazing things coming this year.

[Genesis3800]

Hey @dimaMachina lots of love and regards to you for what you've built. Really excited for Nextra 3. Do you have a rough timeline right now for when it might be ready for stable release?

Thank you 🙌. The stable release will be released once I will polish own Nextra 3 docs to include new changes, I can't say when it will be done. Also, I already started work on Nextra 4 with app router support, so more amazing things coming this year.

Haha fair enough. We at my work are looking forward to versioning support, plus the upgrade to _meta.tsx . If there's any way I can help (I am a technical writer) please let me know.
It'll be an honor if I can help with the release in any way.

[dimaMachina]

@Genesis3800 thank you! It would be a huge help with v3 release 🙏.

If you want to help with docs updates

• please go to v3 alpha #2245, and use this PR as base branch
• once you are v3 branch run pnpm dev:website to run nextra.site locally
• go over all existing docs and update them according to the-guild.dev/blog/nextra-3 changes
• try to create separated PRs to make review easy