Docs: Write page in docs similar to "Thinking in React"

[gmoniava]

What is the improvement or update you wish to see?

App router has brought some changes in terms of how you think about writing applications with react, especially for people coming from SPA background. Now you have to "think in Nextjs": Which components should be client components? Which components should be server components? Can we share data between them? What are some best practices of using them together?

People might have confusions about this topic, there was a related post about it on reddit. Although the person asking that question already had experience with Nextjs.

IMHO one of the best ways to clear up such confusion is to write an article where you explain all this stuff based on a concrete example, a concrete web app. Show how you would write such a web app using Nextjs and explain also the "thought process" along the way. Similar to this: https://react.dev/learn/thinking-in-react

Is there any context that might help us understand?

n/a

Does the docs page already exist? Please link to it.

n/a

[icyJoseph]

Not exactly what you want, but: https://github.com/vercel/app-playground

And as to improved docs, while I agree with the premise, I'll take a pessimistic stance here. People don't read those as much as they should. Nor do they create testing playgrounds to experiment themselves. Looking at someone else's repo, is great, but you ought to write some code yourself too. It takes about 10 seconds to run yarn create next-app my-test-number-99

This section, https://nextjs.org/docs/getting-started/react-essentials, already covers a lot of concepts, but for most people, a 2 minutes 🔥 ⛵ video is more appealing, it is what they want, or in some cases can, watch to get up to speed. Buying the a "become an X in 5 minutes" magazine doesn't quite work.

There's lots of noise out there, but I'll throw in my take in going from, Pages Router to, level 0 App Router:

• Notice that Client Components are the components you have used up till now: https://github.com/reactwg/server-components/discussions/4 - they are pre-rendered server side, and hydrated once in the client
• Notice that a lot of those Components, don't really need a client side JavaScript function to describe them, that is hydration is overhead for those. They are sort of, bones to the muscle that are the components that actually do create user interactivity. They are static if you will.
• Notice that "React Server Components" as a tech stack, is a contract, where you tell React, that some sections of the React tree, ought to behave as they did before, aka Client Components, and you do that by labelling them with 'use client', this results in a Client Tree
  • I think this is potentially a counter-intuitive bit, necessary because server side code ought to be kept private, and that's the default chosen
• For other cases where there's no such use client label, React does a server side render, and creates a Server Tree
• React knows how to patch/weave together these trees so that you app is consistent with state, and data flowing through it.

Once you arrive to this point, you can see that there are other possibilities, such as fetching on the server, caching, streaming, etc, deferring to client rendering, SEO, entire pages that have no JS hydration payload, yada yada. Naturally, there ought to be more possibilities once React "integrates" with the server environment, rather than being just a function that returns a dehydrated HTML string.

Edit

I think, eventually, the Vercel team will come up with a Learn tutorial, similar to the one for Pages Router. I think that'll have the potential to actually drive home a bunch of the concepts from App Router.

[gmoniava]

@icyJoseph hey thanks for comment but:

Looking at someone else's repo, is great, but you ought to write some code yourself too

I didn't recommend looking at the repo, please have a good look at "Thinking in react" page to get a feeling on what kind of tutorial I recommended. Repo would be a result. But point of the article would be to show how to "think in Nextjs".

but I'll throw in my take in going from, Pages Router to, level 0 App Router

Like I said please keep in mind there are people coming from SPA background, who haven't used pages router.

[icyJoseph]

I had to expand a bit the "pessimistic" position, so I did not necessarily mean that you suggested looking at repositories, but that even in the presence of great docs, people skip them.

That being said, like I said, I agree with the premise.

• https://nextjs.org/learn/foundations/how-nextjs-works

For example there's a series of steps in the above link, which, in my opinion at least, do what you ask for. It is generic enough that you can then just pick up https://nextjs.org/docs/getting-started/react-essentials next

And yeah there's no unified document, which again, I agree with having that. Even more, I think a Learn experience as the above will be necessary for the App Router, and it'll most likely land some time in the future.

You'd be surprised to learn how little difference theres' between "SPA Background" and Pages Router.

[gmoniava]

For example there's a series of steps in the above link, which, in my opinion at least, do what you ask for.

@icyJoseph

If you refer to series of steps like "compiling, minifying, bundling, ..." which are on that link I didn't ask for that. I asked for explaining how to use server and client components based on some concrete example.

Actually indeed the "React essentials" page touches on some things which I asked for, however, and this is what I suggested, imho those things are best explained when you explain them with a particular application in mind - like the "thinking in react" does using the filtered table example.

Finally one more note, the article I am referring to "Thinking in React" is not only showing you how to write some component in react, it also shows you the "thought process" that goes along with creating that component.

[leerob]

We're working on this! The entire /learn course will be updated to walk through the new App Router concepts.

[leerob]

Btw, I responded to that thread here: https://www.youtube.com/watch?v=-YO_z14dUyI

[github-actions[bot]]

This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.