Rewrite "Create" page to improve explanations #7618
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Size changes📦 Next.js Bundle Analysis for react-devThis analysis was generated by the Next.js Bundle Analysis action. 🤖 This PR introduced no changes to the JavaScript bundle! 🙌 |
|
Co-Signed |
|
have read through all of it and this reads so much better. primarily the fact that there's now a very clear "manual setup" ("Start from scratch"). regardless of what tools are used in that, its the piece which was missing before and all other frameworks seem to have it. |
| @@ -55,61 +76,119 @@ If you're new to Expo, check out the [Expo tutorial](https://docs.expo.dev/tutor | |||
| Expo is maintained by [Expo (the company)](https://expo.dev/about). Building apps with Expo is free, and you can submit them to the Google and Apple app stores without restrictions. Expo additionally provides opt-in paid cloud services. | |||
|
|
|||
|
|
|||
| ## Other options {/*other-options*/} | |||
| ### Other Frameworks {/*other-frameworks*/} | |||
There was a problem hiding this comment.
what makes these frameworks "other"?
the following sentence suggests its because they are up-and-coming (i.e. early stage right now). is that true?
it may be worth briefly noting why these don't make the "main list" (not necessarily individually, just what makes this overall section its own section)
|
This is a fantastic enhancement of the docs. Would be tremendous to see this land! |
|
This is excellent work. Thank you @markerikson |
|
|
||
| <Note> | ||
| <TerminalBlock> | ||
| npx create-vite@latest my-app --template react |
There was a problem hiding this comment.
It's better to use the TS template
| npx create-vite@latest my-app --template react | |
| npx create-vite@latest my-app --template react-ts |
There was a problem hiding this comment.
It’s not, I assume a beginner will start with JS not with TS
There was a problem hiding this comment.
Co-signed! A beginner who needs the hand-holding of this docs page to start a new project would likely benefit from understanding React detached from TS first.
There was a problem hiding this comment.
Perhaps just present both options, a developer who is new to React but not new to JS/TS might assume the react template is typescript.
npx create-vite@latest my-app --template react(-ts)
or just mention that you can use react-ts for a typescript project.
There was a problem hiding this comment.
I'm of the opinion that you probably should learn some typescript before react anyway as in, in your first two hours of your JavaScript learning journey, you really should be moving over to Typescript. It's been easier then ever to write applications in TypeScript then it has been before (libaries are a different matter, props to you all); it's mostly function declarations anyway.
There was a problem hiding this comment.
TypeScript adds a lot of friction if you're a beginner. If the purpose of this is to make it as easy as possible for beginner engineers to try out React then we should remove as many roadblocks as possible. TS is a roadblock (if an important one).
The community and education resources will push them towards TS eventually anyway. We don't need to solve that problem here and now.
I would, however, be in favor of including a note that TS is recommended.
There was a problem hiding this comment.
I'll second having the note and including the ts templates @doug-stewart . Lot to be said for the broader cosystem to be sure
|
|
||
| To improve app performance, you can use additional [rendering patterns](https://www.patterns.dev/vanilla/rendering-patterns) like server-side rendering (SSR), static site generation (SSG), and/or React Server Components (RSC). You can also implement code splitting to break your app into smaller bundles that can be loaded on demand and improve loading times. | ||
|
|
||
| If you start from scratch, these patterns will require more work to implement yourself and can be harder to get right, and adopting them may require a more significant migration effort (which is why we recommend using frameworks as the default approach ). |
There was a problem hiding this comment.
| If you start from scratch, these patterns will require more work to implement yourself and can be harder to get right, and adopting them may require a more significant migration effort (which is why we recommend using frameworks as the default approach ). | |
| If you start from scratch, these patterns will require more work to implement yourself and can be harder to get right, and adopting them may require a more significant migration effort (which is why we recommend using frameworks as the default approach). |
|
|
||
| ### What About Server Components? {/*server-components*/} | ||
|
|
||
| The frameworks we recommend also include support for React Server Components. |
There was a problem hiding this comment.
I'm not the biggest fan of this line at this point in time as App Router is still the only game in town for RSC's (if your shipping on Waku you have my respect and admiration). If we put it in and React Router doesn't ship RSC's this year it'll look very silly.
| The frameworks we recommend also include support for React Server Components. | |
| At this point in time only Next.js App Router has support for React Server Components; however we are working with the other frameworks we recommend to bring support to those frameworks |
|
This is better. |
|
|
||
| In some cases, CSR is the right choice for a page, but many times it's not. Even if most of your app is client-side, there are often individual pages that could benefit from server rendering features like [static-site generation (SSG)](https://developer.mozilla.org/en-US/docs/Glossary/SSG) or [server-side rendering (SSR)](https://developer.mozilla.org/en-US/docs/Glossary/SSR), for example a Terms of Service page, or documentation. | ||
|
|
||
| Server rendering generally sends less JavaScript to the client, and a full HTML document which produces a faster [First Contentful Paint (FCP)](https://web.dev/articles/fcp) by reducing [Total Blocking Time (TBD)](https://web.dev/articles/tbt), which can also lower [Interaction to Next Paint (INP)](https://web.dev/articles/inp). This is why the [Chrome team has encouraged](https://web.dev/articles/rendering-on-the-web) developers to consider static or server-side render over a full client-side approach to achieve the best possible performance. |
There was a problem hiding this comment.
Server rendering generally sends less JavaScript to the client
Is that always true? In my understanding with SSR the browser would receive the same amount of JS (but doesn't need it for first paint,so first paint is faster)
There was a problem hiding this comment.
Only certain content is rehydrated. If you had a component that simply output some simple DOM with no interaction or client-side children it wouldn't get rehydrated and so your bundle would be comparatively smaller.
So while not always true it would be generally true in principle.
There was a problem hiding this comment.
Only certain content is rehydrated.
This is not true for standard SSR à la Next, but is with framworks focusing on "islands" like Astro. Typical hydration absolutely is full-page and results in no less JS than SPAs (usually slightly more, if anything, as it needs the hydration & render code paths).
Definitely shouldn't ship saying this as it's quite untrue in the context of React. Those articles are referring to pages lacking hydration as that's a rather different issue.
|
|
||
| The frameworks we recommend all provide the option to create a [client-side rendered (CSR)](https://developer.mozilla.org/en-US/docs/Glossary/CSR) app. | ||
|
|
||
| In some cases, CSR is the right choice for a page, but many times it's not. Even if most of your app is client-side, there are often individual pages that could benefit from server rendering features like [static-site generation (SSG)](https://developer.mozilla.org/en-US/docs/Glossary/SSG) or [server-side rendering (SSR)](https://developer.mozilla.org/en-US/docs/Glossary/SSR), for example a Terms of Service page, or documentation. |
There was a problem hiding this comment.
I'm not sure if I understand this correctly, but imho there is a difference between SSG and SSR in the way that for SSR you need a server at runtime and SSG only at build time. While this is clarified above in `Static Site Generation (SSG)´ section, it's somehow mixed here.
Also the "Terms of Service page" example is a little weak imho. Would you really add server infrastructure only for a ToS page (assuming you don't have JS on the server already)? :-)
Co-authored-by: Mark Erikson <[email protected]>
|
Thanks for submitting! I also spent the holiday weekend listening to feedback and thinking about how to address it. I've submitted #7624 which pulls in many of these changes and more to address the feedback. Note: I'm not including the Web Application Architecture guide from this PR because it's fairly large and will need many iterations on feedback that will take some time before landing. If you want to open a new PR we can iterate on it separately. Closing in favor of #7624. |
|
This is good. Approved ✅ |
* [Blog + Docs] Updates from feedback * Merge in changes from #7618 Co-authored-by: Mark Erikson <[email protected]> * Say the words "Vite", "Parcel", and "Rsbuild" * Tweaks from feedback * re-apply #7615 * merge in #7622 Co-authored-by: elitalpa <[email protected]> --------- Co-authored-by: Mark Erikson <[email protected]> Co-authored-by: elitalpa <[email protected]>
Update (2025-02-17)
The React team opened up a new PR in #7624 , pulled over several changes from this PR, and made some additional tweaks. That's been merged and deployed.
From my standpoint, I think those changes should be sufficient to address the main concerns:
I'd say this is a win for everyone!
Summary (Original)
This PR revamps the "Creating a React App" setup instructions page to offer better guidance on how to start a new React project. It also converts the existing "Building a React Framework" page into a page titled "Web App Architectures", which is designed to offer entry-level overviews of concepts like MPA/SPA/SSG architectures, concerns like routing and data fetching, and things to consider when deciding on appropriate architectures for your app.
Rendered Previews
Here's the PR previews for the pages I reworked:
and a couple screenshots of the "Create" page:
Context and Background
The React team just announced they were sunsetting Create React App. As part of that, they also revamped the "Create a New React Project" page and added the "Building a React Framework" page.
These changes were highly anticipated, and the updates to the "Create" page in particular were much needed. However, the reactions on social media in the last few days have shown that the React community still had a lot of confusion and mismatched expectations for what the docs should recommend.
Some of the major concerns included:
That led to numerous debates across social media in the last few days, with mostly negative feedback. I also saw comments from the React team trying to express why they felt the recommendations made sense, but also confused as to why people had these concerns.
I'd previously provided review feedback on the draft versions of these pages. Some of that feedback made it into the merged PR, but a fair amount was not.
Rather than try to write up more review feedback, I felt it would be most effective if I were to go ahead and write up a draft of the docs changes that I feel would most improve the explanations and guidance, while keeping as much of the existing React team recommendations and explanation content as possible.
Changes
"Creating a React App"
The major goals were to better explain the "why frameworks?" topic, and provide specific guidance to users who are learning or looking to use a simpler project setup.
<h3>under "Recommended Frameworks".#bleeding-edge-react-frameworksto#recommended-react-frameworks(and updated links across the site)"Web App Architectures"
The "Sunsetting CRA" blog post and "Building a React Framework" pages had a lot of very good material explaining concepts related to app architectures, but they were mixed together and needed more context for why some of these concepts matter.
I started by renaming "Building A React Framework" to "Web App Architectures". Then, I added several handwritten sections explaining concepts like MPA/SPA/SSG, and cut-and-pasted several explanations from the blog post and combined them together into a more coherent and useful set of explanations and guidance.
Status
This was pretty hastily whipped up over about 5 hours of writing, but I feel pretty good about where this is at.
I think the changes to the "Create" page are exactly as I would recommend it. I think I struck a good balance between maintaining the existing "framework" recommendations, explaining why the React team has those recommendations, acknowledging that React is used in a variety of ways, and providing guidance to learners or people who want to tackle setting up a project themselves.
I'm sure the "Web App Architectures" page needs some editing to make the content flow a bit better, but I think having all these pieces on one explainer page is going to make it much more useful.
I've shown this to some folks like @jherr and @tannerlinsley , and they agree this is a significant improvement.
Merging this PR won't magically make all the complaints and confusion go away. But I do legitimately think that this should address the major outstanding complaints and confusion from the community about how to get started with React, and everybody wins as a result:
Overall, I do think this PR could be merged as-is, but I'm also happy to work with the React team to make edits and refine the explanations!