Hmm ... 💭

[nelsonic]

Please Don't Read This! 🙏

I don't like being "negative" but I know that I cannot fully convey my experience without appearing "negative".
Ultimately, Devs building Nextra have built it for their own needs and have included the features their community have requested/contributed.

Throwing Stones?

I live in a proverbial "glass house" with extra large windows ... 🪟
We have many projects on GitHub with varying degrees of completion/maintenance.
But none of the ones with traction are abandoned/ignored.
We regularly update the packages that have thousands of stars, millions of downloads and people using them
even when it takes time away from our current work.

What?

At the time of wrIting Nextra is Used by 13.3k and has 10.9k Stars https://github.com/shuding/nextra

I should have voiced my "concerns" about this sooner, but I wanted to give it a "fair" chance before commenting.

Specifically

1. 337 issues open. Most have zero comments or acknowledgement from the Authors/Maintainers. 💬 0️⃣

https://github.com/shuding/nextra/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-desc

2. There are 67 PRs with a few more than 2 years old and no comments from the Authors/Maintainers of the project.
   https://github.com/shuding/nextra/pulls?q=is%3Apr+is%3Aopen+sort%3Acreated-asc

e.g: shuding/nextra#315

It's a +4 −5 and only 2 Files changed PR that looks fine to me. 👌
But no comment from the Authors/Maintainers ... ⏳
just a check-in-comment from @TheMikeyRoss 21 months later indicating it was still an issue for them. 😖

@maltejur saw your PR: shuding/nextra#315 if you see this, are you still using Nextra? 💭

This is not to say that Pull Requests are not being merged, they are.
e.g: shuding/nextra#2981 merged by the 2^nd highest contributor with no review. 🤷‍♂️

Pay attention to the commit message: https://github.com/shuding/nextra/pull/2981/commits

Speaking of contributors: https://github.com/shuding/nextra/graphs/contributors

there are two main "guys", the owner - Shu who works at Vercel - and The Terminator: https://github.com/dimaMachina

Who appears to be freelance: "hire me". 💭
Both seem perfectly competent. As are the remaining frequent contributors. 👍

Build Failing on main

The build is failing on the main branch and there is no indication of priority for fixing it. ⏳
https://github.com/shuding/nextra/actions?query=branch%3Amain

With that many people using your project, having a consistent CI should be a priority.

Homepage ...

At the time of writing this is the Nextra Home Page: https://nextra.site/

It defaults to the dark theme because system is selected in the bottom-right of the screen.
Dark cards on a dark background ... was this tested for contrast? 🤷

Page Speed Insights

https://pagespeed.web.dev/analysis/https-nextra-site/62p078my3z?form_factor=mobile

1.4s to load the page isn't bad. but they could definitely improve it if they wanted to.

Accessibility is a 90 (i.e. pass) despite not having a lang attribute:

You'd think a site generator that offers I18n out-of-the-box would set the lang attribute ... 💭
This brings us neatly to "features" ...

What Features does Nextra "give" us?

Google Analytics appears to work, but there is no documentation for it; ref: shuding/nextra#2137

Sitemap + Indexing

Since the early web there has been a standard for indexing all pages on a site: https://en.wikipedia.org/wiki/Sitemaps
There is a community package for this: https://www.npmjs.com/package/next-sitemap
But it has to be done manually for your site: shuding/nextra#419 (comment)

https://nextra.site/sitemap.xml

This is basic SEO best practice, still 100% relevant in 2024:
https://www.google.com/search?q=are+sitemaps+still+relevant

https://developers.google.com/search/docs/crawling-indexing/robots

Similarly with robots.txt
Visiting https://nextra.site/robots.txt you will see a 404:

shuding/nextra#1402 closed by [The Terminator] with no comment/explanation. 👎
Referenced in: shuding/nextra#1421 but doesn't appear to be a feature in V3 ...

Sadly, I don't have time to keep writing this right now. Gotta get back to work-work; which is using Nextra for /docs ...
But I cannot help but feel that we are missing a few key features that are going to be unnecessarily difficult to add to Nextra ... 💭

[TheMikeyRoss]

Something similar happened with https://github.com/jaredpalmer/tsdx

And seeing how shadcn-ui has almost 600 open PRs and is only maintained once a week (sometimes longer)

It seem that the story goes like this:

1. A competent and smart developer creates an open source project
2. The project gains popularity and becomes loved and used by many.
3. The dev behind the project gains recognition and reputation
4. Vercel hires that dev
5. Either, that open-source project gets less attention and slowly gets abandoned. Or, vercel acquires the project.

Similarly, Netlify killed content-layer. See contentlayerdev/contentlayer#429

[nelsonic]

@TheMikeyRoss makes sense. 🙃
Vercel are certainly following the Blitzscaling path: 🚀
https://news.crunchbase.com/cloud/vercels-cloud-web-applications-funding-valuation-accel/

At this sort of valuation they will have to sell to Google sooner or later. 🏦
At that point all the original creators of the various frameworks will cash-out 💰
and sail off into the sunset ⛵
leaving the projects in the hands of caretakers. 💭

[lacymorrow]

You say it like it's a bad thing!
It's a shame when the project loses a maintainer, but even a small open-source project is a huge task for one person.

The missing piece is a community of maintainers.

It seem that the story goes like this:

1. A competent and smart developer creates an open source project
2. The project gains popularity and becomes loved and used by many.
3. The dev behind the project gains recognition and reputation
4. Vercel hires that dev
5. Either, that open-source project gets less attention and slowly gets abandoned. Or, vercel acquires the project.

[TheMikeyRoss]

You say it like it's a bad thing!

The only bad thing is the project dying. And it's unfortunate that the project creator doesn't pass the torch to someone else or to a group of people.

Someone made contentlayer2 just because the original creator of contentlayer didn't add maintainers despite many people offering their help.

[Zamoca42]

Someone made contentlayer2 just because the original creator of contentlayer didn't add maintainers despite many people offering their help.

Given this discussion about open-source project maintenance and the mention of contentlayer2, do you think a Nextra 2 might be needed for similar reasons?

[nelsonic]

@Zamoca42 no. That would be confusing given that Nextra is about to release a v3 ...
The Nextra devs/maintainers are doing a good job with the project - for the needs of their community.👍
What is required a complete re-think of documentation sites. 💭

[lacymorrow]

What is the ideal future for this or other docs site? What would you like to see implemented?

[TheMikeyRoss]

When documentation sites are done right, they become a paid SaaS, See mintlify

[nelsonic]

@TheMikeyRoss indeed. Mintlify does look good. At least superficially.
There are still many features missing e.g: Internationalization

Surely I'm not the first person who has searched their docs for i18n ... 🤷‍♂️
We have a baseline (non-negotiable) need for our Docs site to be available in 3 languages.
So Mintlify immediately rules themselves out.
Then there's the price: $4200/year for "Pro" is silly money for a docs site.
Obvs in the context of the cost of a senior engineer it "pays for itself" very quickly if it has all the needed features.
But it really does not; not even close! And being Closed Source means we have to wait for the features to be added. ⏳
Pass.

It's increasingly looking like we will need to craft our own custom solution. 🙃

[TheMikeyRoss]

Then there's the price: $4200/year for "Pro" is silly money for a docs site.

Absolutely! And it feels extremely disproportional to what it actually costs them.

There's an oldie bookstackapp.com (PHP 😞).
But I just dug into it and it seems they've been discussing i18n for 7 years now See feature request 😅

I have a tingling feeling that there's a well-made, well-maintained, open-source documentation tool out there, I just haven't discovered it yet.

[Zamoca42]

I found two options worth looking into:

• fumadocs
• content-collections

I haven't examined them in depth, but they seem promising as potential open-source documentation solutions. Might be worth checking out as alternatives to the pricier options discussed.

[LuchoTurtle]

@Zamoca42 thanks for sharing https://github.com/fuma-nama/fumadocs, I've been taking a look at it and it almost seems like a good "quasi drop-in replacement" for Nextra. It seems to have most (if not all) the same features as Nextra, with some other neat ones. It also looks to be more actively maintained, as well.

They've a comparison with Nextra in their homepage -> https://fumadocs.vercel.app/docs/ui/comparisons#nextra.

[TheMikeyRoss]

@Zamoca42 fumadocs was exactly what I was looking for, thanks!

[nelsonic]

Fuma doesn’t come close to covering our needs. Here’s our list off the top of my head: dwyl/product-roadmap#49

[TheMikeyRoss]

Here’s our list off the top of my head: dwyl/product-roadmap#49

Oh I see, that's a pretty comprehensive list.

I think it's extremely rare for an open-source doc site project to have a client CMS attached to it by default since the targeted demographic is devs who're expected to write .mdx files or fetch them remotely from somewhere.

You'll most likely have to deeply integrate a CMS open source project like Strapi or Keystone to a docs site like fumadocs or nextra.

Would love to see an open source Docs+CMS combo project (kinda like a mintlify alternative, although mintlify editor uses git for CMS).

I will keep an eye around 👀

[nelsonic]

@TheMikeyRoss agreed, that's kind the point of opening this issue. 👍
We have a decent list of features on our Roadmap 🗺️
and have surveyed the existing landscape and found it lacking ... 😕
Nextra doesn't have a "backend" by default/design. 🙅
Which is good for people who don't want one, but makes building more advanced features tedious.
We want to have auth so that we can protect certain content,
doing that in Nextra via next-auth was way over-complicated
and doesn't come close to meeting our needs.

Attempting to "deeply integrate" a CMS to a docs site is a duct tape solution. 🩹

Sadly, despite the hype, Next.js is not the ideal framework for building this.
It makes building anything interesting (realtime) way more complex than it needs to be. ⏳
What "interesting" features does a Docs site need...?
Analytics without surrendering data/privacy to a 3^rd party. 📈
Collaboration on editing docs. Without this feature we are stuck using tools that do have realtime colab like Miro, Figma, Notion, Google Docs, etc. and then having to copy-paste into the docs repo. 🤦‍♂️

Anyway, if you discover something please share. 🙏

[TheMikeyRoss]

oh don't get me started with next.js, I'm basically in a Stockholm Syndrome relationship with it. Once they deprecate the pages router then I'm out.

After that I'll probably look through vue/nuxt, Unlike Next.js, Nuxt seems to have a healthy progression pace and they're NOT adding new experimental features left and right in production. Also, I think they have a cool & calm community similar to Astro's

[zigang93]

Can try https://docusaurus.io/ from meta open source

[nelsonic]

@zigang93 we were using Docusaurus before Nextra. 🦕
There are pros and cons to both. But neither fits our use case and Docusaurus is even more convoluted to extend with the features we need.
Neither of these Docs tools has a “backend” so adding anything minimally advanced/custom is a chore where you have to “fight the framework”. 😔

If I had infinite time I would just build something better. Alas time is scarce. ⏳😕

[nelsonic]

Just tried searching for something (which I consider basic) in the Nextra docs ...
Decided to search SO: https://stackoverflow.com/questions/tagged/nextra

Really not a lot of questions/answers for a framework that has 10k+ stars. ⭐ 💭

[nelsonic]

One of the things that has annoyed me a lot about Nextra is having multiple _meta.json files (one per directory) to configure how the link text appears in the Side and Top Nav:
e.g:

I would much rather have a single sitemap.yml (or sitemap.json) file at the root of the project that allows optionally configuring all pages regardless of nesting level and avoiding duplication of files and effort.
I often have 3+ _meta.json files open simultaneously and it's a context-switching pain. 🙃

[nelsonic]

Same goes for having many /assets directories spread across the project ... would definitely prefer a single place to store all assets even if then organised into subdirs e.g: /assets/engineering, /assets/client, /assets/frontend, etc.

[LuchoTurtle]

While _meta.json is non-negotiable, you definitely don't need to have an assets directory in each subdirectory. You can have a single place to store it, like you've mentioned. In the case of A, we went with it because that's how they did it in Docussaurus.

[nelsonic]

Yeah, I've noticed that I can easily reference a file in a root /assets dir but it's a hangover from Docusaurus ... 🙃
The _meta.json per directory is lame and it might get even more complex with allowing JS execution in the file: shuding/nextra#852 ultimately, this could/should be streamlined.

[nelsonic]

These types of errors which give exactly zero insight as to where the error occurred in the codebase ... 🤦‍♂️

Unhandled Runtime Error

Error: Hydration failed because the initial UI does not match what was rendered on the server.
See more info here: https://nextjs.org/docs/messages/react-hydration-error

What is a non-technical person attempting to edit a document in Nextra meant to do with this? 🤷‍♂️
Why does a documentation site even need to have any client-side rendering? 😕

[nelsonic]

Another markup error crashing the whole site with no helpful stack trace:

The page in question /pages/index.mdx has only one <span> tag and it is appropriately closed:

I've scoured this page for several minutes and not found any tag that does not have the appropriate closing tag.
And yet, still get this silly error. 🤦‍♂️

[lacymorrow]

You need more newlines. MDX is injecting a <p> tag somewhere.

[lacymorrow]

Nextra 3 was announced...

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

[nelsonic]

@lacymorrow indeed: #15 with breaking (backward incompatible) changes. 🙃
We got a @dependabot notification for it this morning. 🌅
Breaks our CI ... 💔 🤦‍♂️ (in a private project ...)
2.8kloc+ changes in pnpm-lock.yaml ...

Not exactly a "quick" review ... ⏳ 🙄

Some project maintainers really don't consider the value of the time of the "users" of their framework. ⏳ 💸 🔥
Obviously anything using React will have many updates as noted in dwyl/learn-nextjs#12 💭
This isn't the worst lock file update we've seen recently.

[lacymorrow]

I promise you, features to a wider base are more important than an individual's time savings 😁

As usual with open-source, I'm sure they will offer you a full refund.

Jokes aside, conflicts in a lock file can be resolved easily. Delete the file and re-run pnpm i