Updates from feedback #7624
Updates from feedback #7624
Conversation
Co-authored-by: Mark Erikson <[email protected]>
|
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. 🤖 Five Pages Changed SizeThe following pages changed size from the code in this PR compared to its base branch:
DetailsOnly the gzipped size is provided here based on an expert tip. First Load is the size of the global bundle plus the bundle for the individual page. If a user were to show up to your website and land on a given page, the first load size represents the amount of javascript that user would need to download. If Any third party scripts you have added directly to your app using the Next to the size is how much the size has increased or decreased compared with the base branch of this PR. If this percentage has increased by 10% or more, there will be a red status indicator applied, indicating that special attention should be given to this. |
|
|
||
| <Note> | ||
| * [Vite Create React App migration guide](https://www.robinwieruch.de/vite-create-react-app/) |
There was a problem hiding this comment.
What's the best guide for migrating from CRA to Vite? (cc @yyx990803)
There was a problem hiding this comment.
We can work on an official one and later send a PR.
There was a problem hiding this comment.
Thanks! To be honest, not having clear and official guides (and I hadn't actually tested these, like i have the framework guides) were the only reason I didn't include this section in the original draft, and just linked to our new docs. That clearly sent the wrong message, and I needed to add this quickly, so it would be nice to get more official guides.
|
|
||
| <Note> | ||
| * [Vite Create React App migration guide](https://www.robinwieruch.de/vite-create-react-app/) | ||
| * [Parcel Create React App migration guide](https://stackoverflow.com/a/49605484) |
There was a problem hiding this comment.
What's the best guide for migrating from Parcel? (cc @devongovett)
|
|
||
| </Note> | ||
| </DeepDive> |
There was a problem hiding this comment.
@ryansolid does this feel less "begrudging" and more in line with other library recommendations?
There was a problem hiding this comment.
I was away for the weekend.. Only comment is "unusual constraints" still carries a tone of someone doing something wrong. But generally I think this will do it. It's tricky because there is a perceived history here, even if I don't think it's completely fair. Perceptions being as such makes the situation more delicate than would otherwise be merited.
There was a problem hiding this comment.
Yeah, I can see how that has the wrong tone.
The intent is to cover use cases like a VSCode plugin, chrome extension, or game which are (let's be real) uncommon and don't need URL routing integrated into data-fetching and will never need server features because they're not deployed to the web. But framed in a way where folks who are new won't mistakenly pattern match themselves into this category and go down the wrong path and get locked in to CSR only.
Do you have suggestions on wording to clarify this and soften the tone?
|
Glad to see the feedback being incorporated! |
|
Thanks for working on this! Ideally I'd still like to see the actual mentions of Vite/Parcel/Rsbuild directly on the "Creating a React App" page :) I know it's a sticking point, but it's one of the things contributing to the complaints I've seen. That said, the revised "Build a React app from Scratch" page is a significant improvement in explanations and details at this point! A few other thoughts:
|
There was a problem hiding this comment.
You can see in the screenshots that when copying the commands they don't work because markdown text gets transformed (fix in #7622 ).
Preview of the Page (notice there are no double dashes -- as in the code) :
When copying the commands :
|
@markerikson thanks for the feedback, I made these updates:
I considered the section you wrote, but it was confusing and inaccurate IMO. It starts with "if you've built a client-side [...]" but this page is for creating a new app, in which case you haven't built anything, which is confusing. It also says that SPAs don't need Node to run, but they do need node in CI to bundle the app, and it doesn't distinguish between CSR, SPAs, and SSG (which also all need Node in CI). It also says SPAs "can work with backends written in any language" which implies SSR can't, which is misleading at best. Most importantly though, it buries the "all of the frameworks support SPAs" point to the end of the paragraph, but this is one of the biggest pieces of FUD in the community right now so I think it needs to be short, clear, and direct. |
|
Gotcha. Yeah, the Node mention I put in there was intended to cover running in production, vs bundling in CI, since "Do I need Node to run React?" is a fairly common question. I was also trying to indicate that SPAs work well if your backend isn't JS. |
Co-authored-by: elitalpa <[email protected]>
|
Going to merge, if there are better guides to link to or tweaks to make we can fix forward 🚀 |
|
Thank you for listening to the feedback and making these updates! From my standpoint, I think this should be sufficient to address the main concerns:
I'd say this is a win for everyone! |
|
Heh. Just thought of one more thing that would have been good to pull over: the "DON'T USE CRA!" note I had added at the bottom :) |
|
Oh yeah, I want that in there as well |
|
@markerikson I kinda of added that, I merged it with the note that was on the Installation page. 
This is the page that you go to when you click "Installation" (Creating a React App is collapsed so you can't even click directly to it) so I think it makes the most sense there. |
|
|
||
| For existing apps, these guides will help you migrate to a client-only SPA: | ||
|
|
||
| * [Next.js’ Create React App migration guide](https://nextjs.org/docs/app/building-your-application/upgrading/from-create-react-app) | ||
| * [React Router’s framework adoption guide](https://reactrouter.com/upgrading/component-routes). | ||
| * [Expo webpack to Expo Router migration guide](https://docs.expo.dev/router/migrate/from-expo-webpack/) | ||
|
|
||
| Create React App will continue working in maintenance mode, and we've published a new version of Create React App to work with React 19. | ||
| ## How to Migrate to a Build Tool {/*how-to-migrate-to-a-build-tool*/} | ||
|
|
||
| If your app has unusual constraints, or you prefer to solve these problems by building your own framework, or you just want to learn how react works from scratch, you can roll your own custom setup with React using Vite, Parcel or Rsbuild. |
There was a problem hiding this comment.
Saw this PR a bit late but I want to point out the "unusual constraints" phrasing here is among those that makes users who find Vite + React just fine feel that their preference is being invalidated - when in fact there are massive amount of users falling into this category.
As evidence, here's a chart comparing number of plain Vite + React users (calculated from total of the two official Vite React plugins minus Remix) vs. Next - the numbers are quite close and we expect this to overtake Next at some point.
Another point I want to make is this section is talking about "Migration" - a term that mostly applies to existing applications. Most existing CRA apps likely already have their routing / data fetching implemented in some way (e.g. with older versions of React Router). Moving to something like Vite is the most proven and safe path to adopt modern tooling, without the risk of having to refactor their (currently working) routing and data fetching logic. I really wouldn't call this "unusual constraints" - rather, this is probably the most practical constraints: replace something deprecated with something that is actively maintained, improve the DX, while minimizing the migration cost / risk.
There was a problem hiding this comment.
I appreciate the feedback. Maybe there's some tweaking we can do to the language here. This specific sentence is just copy pasted from the intro of Build a React App from Scratch. Here we're just trying to explain that you can migrate to a build tool if you want. In the deep dive it says:
Most apps would benefit from a framework, but there are valid cases to build a React app from scratch. A good rule of thumb is if your app needs routing, you would probably benefit from a framework. Just like Svelte has Sveltekit, Vue has Nuxt, and Solid has SolidStart, React recommends using a framework that fully integrates routing into features like data-fetching and code-splitting out of the box. This avoids the pain of needing to write your own complex configurations and essentially build a framework yourself. However, you can always build a React app from scratch using a build tool like Vite, Parcel, or Rsbuild.
The goal isn't to invalidate preferences, because the goal isn't to document preferences at all. The goal is to encourage users to use a setup that will allow them to build the best user experience possible, which means allowing them to integrate data fetching into routing easily, and to opt in to server features if they want instead of getting locked into a network-waterfall prone bloated CSR bundle that requires a lot of work to fix later (fwiw, this isn't a critique of Vite, since solving these problems are for frameworks and not a build tool).
As for the migration pain - you can use all of the same routing you're already using in the migration guides we provided. Both the Next guide and the React Router guide explain the steps to migrate using your existing routing and you can incrementally migrate to the file based routing. I don't think it's fair to developers to frame that as less safe, or more work. There are plenty of stories of pain points migrating from Create React App to Vite (as well as successes).
Also, if we're going to compare usage, we should also include React Router (not just Remix), which has almost as many downloads as Next and Vite React combined. This is important context because it shows that most Vite users immediately install React Router. So most Vite apps are already using React Router (the library), and can choose React Router (the framework) to continue using Vite:
Overview
We received some good feedback on the Sunsetting Create React blog post and new Build a Framework docs. This PR attempts to address some of the main concerns by clarifying the language and migration steps.
Thanks @markerikson for you suggestions in #7618, which I've incorporated many of here, and @elitalpa for fixing the terminal commands so they are copy-pasteable.
Concern 1: no migration steps to a build tool
Heard a lot of feedback that we're not providing migration steps to a build tool for users who have use cases where a framework isn't appropriate. The intent was to direct users to the "build a framework" docs to select a build tool to migrate to, but this wasn't clear. ""
Addresses this feedback by adding links to build tool migration guides in the blog post when a framework is not a good fit:
Concern 2: "building a framework" title unclear
We intended for the "building a framework" page to also cover the use cases where using a framework isn't a good fit or users just want to learn how react works. In those cases, many users will end up building their own framework, so we titled it that, but it's not alway the case that you will need to build a framework (e.g. triplex). To address, this PR re-titles the page to "Build a React App from Scratch", and reframes step 2 as "build common application patterns":
Concern 3: "Create a React app" does not direct users to build tools
Heard feedback that the Create a React App page doesn't direct users to docs to use a build tool. Although the Installation page is the true landing page for the installation steps, which mentions both options, users still seem confused that it's missing. To address, this pulls in the change from #7618 to add a "Start from scratch" option on the Create a React App page:
Concern 4: We "recommend Vite with a framework" isn't well received
Heard feedback "reading this paragraph is the most indicative thing that I've seen that React has completely lost touch. It's justifiable sure... but it isn't React" (post) and that the tone you can read that sound begrudging. The intent of this section was to call out that you can use Vite with a framework, or use it directly to build from scratch, but that's not clear from the text.
Replaced this to "Do I need a framework?" that explains that "there are valid cases to build a React app from scratch":
Other changes
There were a lot of good changes from #7618 under Build a React App from scratch for routing and data fetching. I've pulled those over as well. I'm not including the Web Application Architecture guide from that PR because it's fairly large and will need many iterations on feedback that will take some time before landing, but this PR should incorporate all of the main changes.