Next.js is infuriating

First off, since the sentiment here is really negative, I'd like to say that next.js is actually really good for what it does. You've done a great job at building the software that powers millions of websites at this point.

I think a big part of the negative sentiment derives from the fact that detailed documentation and reference documentation almost non-existant. The documentation mostly tells you what exists, but not how to use them, how they get executed, common pitfalls and gotchas etc etc.

The documentation is written to be easy and friendly to newcomers, but is really missing the details and nuances of whatever execution context a given api is in and does not touch on derived complexities of using react in a server environment etc.

This is a trend across a lot of projects these days - often missing all the nuances and details - writing good documentation is really hard. Finding the balance between making things user friendly and detailed is hard.

Keep it up

Don't you find it problematic, as a framework that's 8 years old to already have reached version 15.x? Assuming they follow semantic versioning and those are 15 different backwards incompatible upgrades?

> Finding the balance between making things user friendly and detailed is hard.

Thanks for the note! Indeed, it is also challenging when experience hides what things are not obvious or necessary to make further connections when reading the docs. It is an area of continuous improvement.

> The documentation is written to be easy and friendly to newcomers, but is really missing the details and nuances of whatever execution context a given api is in and does not touch on derived complexities of using react in a server environment etc.

I think on this particular topic, there had been an assumption made on the docs side, that, listing Edge runtime (when middleware was introduced), as its own thing, that might as well run in another computer, would also communicate that it does not share the same global environment as the underlying rendering server.

I'll do some updates to narrow this down again.

> The documentation mostly tells you what exists, but not how to use them, how they get executed, common pitfalls and gotchas etc etc.

Do you have anymore examples on this. I have been improving the revalidateTags/ Paths, layouts, fetch, hooks like useSearchParams, gotchas with Response.next, etc..

I know the OP post does talk about issues not being responded to, but that trend has been changing. If you do find/remember something as you describe, please do open a documentation issue, pointing to the docs page and the confusion/gotcha - we have been addressing these over the past months.

Don’t think it’s semver.

Most of our upgrades have been fairly painless. Yes, they're not CI-succeeds Dependabot merges, but usually it's basically running the auto codemod and you're done, though I do always scan through the release notes and migration guide. That seems justified for the backbone of our application.

I think it is, that is why it is still unstable, 2 majors changes/year.

I haven't used next.js but it looks like they have mostly automatic/codemod migrations

`npx @next/codemod@canary upgrade latest`

Yes, those have been really decent IIRC - don't remember ever having issues upgrading