Rewrite "Create" page to improve explanations and recommendations

markerikson · markerikson · commit c3b487d6bd20 · 2025-02-16T19:23:59.000-05:00
diff --git a/src/content/learn/creating-a-react-app.md b/src/content/learn/creating-a-react-app.md
@@ -4,21 +4,43 @@ title: Creating a React App
 
 <Intro>
 
-If you want to build a new app or website with React, we recommend starting with a framework.
+React can be used to build apps and websites in a variety of ways. Here's our recommendations for how to create a new React app.
 
 </Intro>
 
+## Ways to Use React {/*ways-to-use-react*/}
+
+React is flexible. You can use it to build full-stack apps with integrated client and server functionality, in standalone client apps that work with any backend or just a browser, or even add React to an existing page generated by a server.
+
+We've found that most React apps have similar needs for data fetching and routing, and benefit from performance patterns like code splitting.  Because of this, we primarily **[recommend using a React-based framework](#bleeding-edge-react-frameworks)** as the best way to build a React app.  These frameworks provide good defaults, integrate these features, and provide room to grow your app over time.  (Similarly, other UI libraries also recommend integrated frameworks - Svelte has Sveltekit, Vue has Nuxt, and Solid has SolidStart.)
+
+If you want a simpler setup or are learning, you can **[start from scratch](#start-from-scratch)** with a lighter project setup, and we have suggestions for common tools that will help get your app going the right way.
+
+To learn more about the different ways to use React, see [the overview of web app architectures](/learn/web-app-architectures)
+
+<DeepDive>
+
+#### Do I Need a Server to Deploy a React App? {/*react-app-deployment*/}
+
+Deploying a React app depends on what tools you use to build the app and what kind of app you're building.
+
+If you've built a client-side Single Page Application or a static content site, you just need a place to upload and host the JS, HTML, and CSS files for your site, and it can fetch data from any server or API as needed.  Single-page apps can be deployed to a [CDN](https://developer.mozilla.org/en-US/docs/Glossary/CDN) or static hosting service, and do not need to run an app server.  This also means that Single-Page Apps do not need Node to run, and can work with backends written in any language.
+
+If your app uses Server-Side Rendering to generate pages, you'll need to deploy the application somewhere that can host your app server.  SSR apps do need Node or another JS runtime to run React on the server.
+
+Note that **all of the full-stack frameworks on this page can also create standalone single-page apps that don't need an app server!**  If you would like to enable features that require a server (like Server-Side Rendering), you can later opt-in on individual routes without rewriting your app, and just change how you deploy it.
+
+
+
+</DeepDive>
+
 ## Recommended React frameworks {/*bleeding-edge-react-frameworks*/}
 
-These recommended frameworks support all the features you need to deploy and scale your app in production. They have integrated the latest React features and take advantage of React’s architecture.
 
-<Note>
 
-#### React frameworks do not require a server. {/*react-frameworks-do-not-require-a-server*/}
+These recommended frameworks support all the features you need to deploy and scale your app in production. They have integrated the latest React features and take advantage of React’s architecture.
 
-All the frameworks on this page can create single-page apps. Single-page apps can be deployed to a [CDN](https://developer.mozilla.org/en-US/docs/Glossary/CDN) or static hosting service and do not need a server. If you would like to enable features that require a server (like server side rendering), you can opt-in on individual routes without rewriting your app.
 
-</Note>
 
 ### Next.js (App Router) {/*nextjs-app-router*/}
 
@@ -55,7 +77,7 @@ 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 are other up-and-coming frameworks that are working towards our full stack React vision:
 
@@ -96,20 +118,99 @@ Server Components and Suspense are React features rather than Next.js features.
 
 </DeepDive>
 
-<Note>
+## Start From Scratch {/*start-from-scratch*/}
+
+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.
+
+Starting from scratch gives you more flexibility, but does require that you make choices on which tools to use for routing, data fetching, and other common usage patterns.  The [frameworks we recommend](#bleeding-edge-react-frameworks) have built-in solutions for these problems.  If you want to choose your own solutions, we have some recommendations for commonly-used tools.
+
+### Install a Build Tool {/*install-a-build-tool*/}
+
+The first step is to install a build tool like `vite`, `parcel`, or `rsbuild`. These build tools provide features to package and run source code, provide a development server for local development and a build command to deploy your app to a production server.
+
+#### Vite {/*vite*/}
+
+[Vite](https://vite.dev/) is a build tool that aims to provide a faster and leaner development experience for modern web projects.
+
+<TerminalBlock>
+npx create-vite@latest my-app --template react
+</TerminalBlock>
+
+Vite is opinionated and comes with sensible defaults out of the box. Vite has a rich ecosystem of plugins to support fast refresh, JSX,  Babel/SWC, and other common features. See Vite's [React plugin](https://vite.dev/plugins/#vitejs-plugin-react) or [React SWC plugin](https://vite.dev/plugins/#vitejs-plugin-react-swc) and [React SSR example project](https://vite.dev/guide/ssr.html#example-projects) to get started.
+
+Vite is already being used as a build tool in one of our [recommended frameworks](/learn/creating-a-react-app): [React Router](https://reactrouter.com/start/framework/installation).
+
+#### Parcel {/*parcel*/}
+
+[Parcel](https://parceljs.org/) combines a great out-of-the-box development experience with a scalable architecture that can take your project from just getting started to massive production applications.
+
+<TerminalBlock>
+npm install --save-dev parcel
+</TerminalBlock>
+
+Parcel supports fast refresh, JSX, TypeScript, Flow, and styling out of the box. See [Parcel's React recipe](https://parceljs.org/recipes/react/#getting-started) to get started.
+
+#### Rsbuild {/*rsbuild*/}
+
+[Rsbuild](https://rsbuild.dev/) is an Rspack-powered build tool that provides a seamless development experience for React applications. It comes with carefully tuned defaults and performance optimizations ready to use.
+
+<TerminalBlock>
+npx create-rsbuild --template react
+</TerminalBlock>
+
+Rsbuild includes built-in support for React features like fast refresh, JSX, TypeScript, and styling. See [Rsbuild's React guide](https://rsbuild.dev/guide/framework/react) to get started.
+
+
+### Common Application Patterns {/*common-application-patterns*/}
+
+The build tools listed above start off with a client-only, single-page app (SPA), but don't include any further solutions for common functionality like routing, data fetching, or styling.
+
+The React ecosystem includes many tools for these problems. We've listed a few that are widely used as a starting point, but feel free to choose other tools if those work better for you.
+
+#### Routing {/*routing*/}
+
+Routing determines what content or pages to display when a user visits a particular URL. You need to set up a router to map URLs to different parts of your app. You'll also need to handle nested routes, route parameters, and query parameters.  Routers can be configured within your code, or defined based on your component folder and file structures.
+
+Routers are a core part of modern applications, and are usually integrated with data fetching (including prefetching data for a whole page for faster loading), code splitting (to minimize client bundle sizes), and page rendering approaches (to decide how each page gets generated).
+
+We suggest using:
+
+- [React Router](https://reactrouter.com/start/framework/custom)
+- [Tanstack Router](https://tanstack.com/router/latest)
+
+
+#### Data Fetching {/*data-fetching*/}
+
+Fetching data from a server or other data source is a key part of most applications. Doing this properly requires handling loading states, error states, and caching the fetched data, which can be complex.
+
+Purpose-built data fetching libraries do the hard work of fetching and caching the data for you, letting you focus on what data your app needs and how to display it.  These libraries are typically used directly in your components, but can also be integrated into routing loaders for faster pre-fetching and better performance, and in server rendering as well.
+
+Note that fetching data directly in components can lead to slower loading times due to network request waterfalls, so we recommend prefetching data in loaders or on the server as much as possible!
+
+If you're fetching data from most backends or REST-style APIs, we suggest using:
+
+- [React Query](https://react-query.tanstack.com/)
+- [SWR](https://swr.vercel.app/)
+- [RTK Query](https://redux-toolkit.js.org/rtk-query/overview)
+
+If you're fetching data from a GraphQL API, we suggest using:
+
+- [Apollo](https://www.apollographql.com/docs/react)
+- [Relay](https://relay.dev/)
+
+
 
+### Improving Application Performance {/*improving-application-performance*/}
 
-#### Do you recommend Vite? {/*do-you-recommend-vite*/}
+The build tools listed above default to building single page apps (SPAs).  SPAs can be simpler to start with, but can also lead to slower overall app performance due to loading large amounts of JS.
 
-We provide several Vite-based recommendations.
+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.  
 
-React Router v7 is a Vite based framework which allows you to use Vite's fast development server and build tooling with a framework that provides routing and data fetching. Just like the other frameworks we recommend, you can build a SPA with React Router v7.
+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 ).
 
-We also recommend using Vite when [adding React to an existing project](/learn/add-react-to-an-existing-project), or [building a framework](/learn/building-a-react-framework).
+See [Web App Architectures](/learn/web-app-architectures) to learn more about possible rendering strategies and other performance improvements, and how to apply these techniques without a framework.
 
-Just like Svelte has Sveltekit, Vue has Nuxt, and Solid has SolidStart, React recommends using a framework that integrates with build tools like Vite for new projects.
 
-</Note>
 
 -----
 
