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:
- There's a clear statement that you can use React without a framework, and direct links to instructions
- Vite et al are mentioned in the setup page and "From Scratch" page
- phrasing / content is much improved
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:
- The new "Create" page mentioned Vite, but still somewhat in passing (a mention of React Router v7 using Vite, and a callout box labeled "Do you recommend Vite?" that mentioned React Router). This is definitely an improvement, but still not quite an actual clear recommendation.
- The "Create" page didn't have any guidance on what tools to use if you're trying to learn React
- The "you can build your own framework (badly)" phrasing is valid, but also confusing to readers who are really trying to just set up an application themselves
- The "Building a React Framework" page felt confusing to many people. It alternated between actual instructions ("Step 1: Install Vite or Parcel"), and theoretical architectural guidance for someone building a framework.
- Guidance on specific tools to use for the common use cases like data fetching and routing were mostly buried in the middle of the "Building a React Framework" page
- Some of the content tone was off-putting to readers
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.
- Reworked the introduction to the page to give better context for how React can be used and why frameworks exist:
- Changed the intro sentence and paragraphs to describe React's flexibility and variety of use cases
- Described why React recommends frameworks ("React apps have similar needs and benefit from good framework defaults"), and moved the mention of other frameworks like SvelteKit and Nuxt to this paragraph. Added bold links to the "Recommended Framework" and "Start from Scratch" sections
- Converted the existing "React frameworks do not require a server" green note into a "Do I Need a Server to Deploy a React App?" expandable deep dive section. Added paragraphs summarizing deployment of an SPA vs SSR app. Kept the "all the frameworks we recommend can generate SPAs" paragraph, at the bottom of this section.
- Updated the "Recommended Frameworks" section:
- Tweaked the recommended frameworks to move the full descriptions into consolidated paragraphs before the install instructions. Gave them all consistent "To create a new $FRAMEWORK project, run: " statements.
- Moved the "Other Frameworks" header to be an
<h3>under "Recommended Frameworks". - Changed the header ID from
#bleeding-edge-react-frameworksto#recommended-react-frameworks(and updated links across the site) - Removed the "React team's full stack vision" section and moved it to the revamped "Web App Architectures" page
- Added a new "Start from Scratch" top-level section that says: "If you are learning React, are not using JS in your backend, only need client-side functionality, or want to design your app configuration yourself, there are other options available for starting a React project from scratch.". Added a mention that you can choose your own tools, but frameworks simplify this.
- Added a note labeled "Should I use the legacy Create React App tool?" that explicitly says "No, it's deprecated, use the tools on this page", and links to the blog post.
- Moved the setup instructions for Vite/Parcel/Rsbuild from the "Building a React Framework" page to here
- Added a "Common Application Patterns" section after that that has section for "Routing" and "Data Fetching". Moved over a couple of the explainer paragraphs from "Building a Framework", added more explanations for why these topics matter. Added a mention that hoisting data fetching into route loaders is recommended for perf. Organized the suggested libraries for each topic into bullets.
- Added an "Improving Application Performance" header after that that notes that SPAs can lead to less-than-ideal perf patterns and frameworks can help, and then links to the new "Web App Architectures" page for more guidance.
"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.
- Added an "Application Architectures" section that explains key concepts you need to understand when deciding what tools to use and how the app will work:
- Wrote an "Architecture Categories" section summarizing MPA/SPA/SSG meanings and tradeoffs
- Cut and pasted the "Rendering Strategies" section into here. (Ended up with some overlap with the section I just wrote, but the additional descriptions and separate axis of explanation may be useful.)
- Added a "Modern App Architectures" section that says "these techniques all overlap, an app might use all of them in different places, frameworks let you pick and choose, SPAs are more limited"
- Added a "Common Application Patterns" section, similar to what I have in the "Create" page, but with more details
- Filled out the "Routing", "Data Fetching", and "Code Splitting" sections with a mixture of the paragraphs that were already here, the additional explanations I wrote in "Create", and the examples in the "Sunsetting CRA" post
- Pasted in the "Why We Recommend Frameworks section from the "CRA" post
- Added an "Architecture Considerations" section to provide some guidance to readers on how to decide
- Added an "Application Types" section that links to Patterns.dev and Jason Miller's "Application Holotypes" article, to provide guidance on what architectures might make sense for a given type of application
- Cut and pasted several existing callouts and sections: "SSR is optional", "SSR is not just for SEO", "What about RSCs?", and "What makes up the React team's full-stack vision?"
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:
- The docs still recommend frameworks as the right way to use React, and now explain the "why" more clearly
- Beginners have a direction on a simpler way to get started
- Everyone who has been asking for a direct recommendation of Vite should hopefully finally be satisfied :)
- The "Create" page explicitly mentions that CRA is dead and to use something else
- Anyone reading the "Start from Scratch" section will also see advice on patterns they can use to improve their app's performance
- The "Web App Perf" page retains the great explanations about why routing / data fetching / code splitting matter (as added in the recent docs update), provides additional context about how these fit into overall app architectures, and provides some more useful guidance for how to evaluate which architectures make the most sense for a given app.
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!