search

shuding / nextra

Simple, powerful and flexible site generation framework with everything you love from Next.js.
https://nextra.site
MIT License
11.21k stars 1.23k forks source link

Nextra 3 #1421

Open dimaMachina opened 1 year ago

dimaMachina commented 1 year ago

below of my thoughts on the next biggest release

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

also this should fix blocked renovate PRs https://github.com/shuding/nextra/pull/1136 https://github.com/shuding/nextra/pull/1083 which one now ESM only

this should fix the following https://github.com/shuding/nextra/issues/1263 and avoid future bugs with redirects of https://github.com/shuding/nextra/issues/1354 https://github.com/shuding/nextra/issues/1402

juliusmarminge commented 1 year ago

You got a rough timeline for this release?

dimaMachina commented 1 year ago

@juliusmarminge nope

pomber commented 1 year ago

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

dimaMachina commented 1 year ago

no plans currently

ecraig12345 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

https://github.com/shuding/nextra/discussions/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 commented 1 year ago

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

https://github.com/shuding/nextra/issues/1054

dimaMachina commented 11 months ago

@dacevedo12 no chances, pr welcome

chakhsu commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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.

GraceWalk commented 9 months ago

I encountered a bug. When I open https://grpcity.js.org/en and manually enter "gPRCity is a simple" in the search bar, an error will be reported.

abenhamdine commented 9 months ago

I encountered a bug. When I open grpcity.js.org/en and manually enter "gPRCity is a simple" in the search bar, an error will be reported.

Which error ? I tried to reproduce it without success

GraceWalk commented 9 months ago

Which error ? I tried to reproduce it without success

Application error: a client-side exception has occurred (see the browser console for more information).

I used "Arc 1.17.2 (43249) Chromium Engine Version 119.0.6045.159"

20231129-103051

abenhamdine commented 9 months ago

I have no error in console, I tried with Chrome Version 119.0.6045.160 (Build officiel) (64 bits), Windows OS You should try with incognito mode, to see if an extension would be the culprit

GraceWalk commented 9 months ago

I have no error in console, I tried with Chrome Version 119.0.6045.160 (Build officiel) (64 bits), Windows OS You should try with incognito mode, to see if an extension would be the culprit

You are correct, it is indeed a browser extension causing the problem. I tried turning off the extension and the search function worked fine. ignore this question

dimaMachina commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

⚠️ 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 https://github.com/shuding/nextra/issues/2023

hariria commented 7 months ago

@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 commented 7 months ago

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

maciejkwas commented 7 months ago

@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 commented 7 months ago

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

Genesis3800 commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

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

If you want to help with docs updates

mmkal commented 1 month ago

Hi, not sure this is the right place to put this, but I didn't want to create a new issue since v3 is in alpha (feel free to mark as off topic and I can post as an issue).

Looks like there's a small CSS bug in ``` blocks (at least, single line ones that don't have a language tag - see the left padding):

Example: https://www.pgkit.dev/packages/migrator - source code here: https://github.com/mmkal/slonik-tools/blob/pgkit/apps/docs/pages/packages/migrator.md

image

It doesn't seem to affect code blocks:

image

Also, the backgroundColor.dark property didn't seem to do anything - note that the above page is in the normal colour even though I set backgroundColor.dark = 'green': https://github.com/mmkal/slonik-tools/blob/pgkit/apps/docs/theme.config.tsx#L24-L27

dimaMachina commented 1 month ago

Looks like there's a small CSS bug in ``` blocks (at least, single line ones that don't have a language tag - see the left padding):

bug, will be fixed

Also, the backgroundColor.dark property didn't seem to do anything - note that the above page is in the normal colour even though I set backgroundColor.dark = 'green'

use 0,255,0 for green

example

https://github.com/shuding/nextra/blob/399c330f43a8cb765b8ff03337d0e781200312b3/examples/swr-site/theme.config.tsx#L65-L68

equinusocio commented 1 month ago

Any hope to see this fixed with v3?

https://github.com/shuding/nextra/issues/1403

The most easy and basic fix is this, just wrap nextra styles in a css layer.

The only solution I found is to run a postintall script that takes the CSS content from node_modules/nextra-theme-docs/style.css and wraps it inside a CSS layer named core, which is our basic layer for core CSS like resets, so we are able to use other CSS layers from the DS

logemann commented 6 days ago

Looks like we cant use Nextra with React19 because of this: https://github.com/shuding/nextra/pull/3037#issuecomment-2304496499

Are there any efforts to upgrade to latest headlessui/react so that we can use Nextra with a React19 NextJS project?

logemann commented 5 days ago

Configuring sidebar menus with explicit definition instead using the folder structure? No thanks. ;-)

Genesis3800 commented 5 days ago

@logemann:

  1. Even now in Nextra, you need to create individual _meta.json files to define sidebar menus with any sort of complexity at all. For example, something like this (that I made recently) requires a bit of refining in the _meta.json
  2. Configuring sidebar menus with explicit definitions isn't unprecedented either, Docusaurus does it that way too.
  3. That being said, I still believe Nextra is better than Vocs.