Blog and docs: Sunsetting Create React App (#7495)

* Blog and docs: Sunsetting Create React App

* fix link

* tweaks

* fix markdown

* clarity + thanks

next-env.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+/// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

src/content/blog/index.md

@@ -4,12 +4,20 @@ title: React Blog
 
 <Intro>
 
-This blog is the official source for the updates from the React team. Anything important, including release notes or deprecation notices, will be posted here first. You can also follow the [@reactjs](https://twitter.com/reactjs) account on Twitter, but you won’t miss anything essential if you only read this blog.
+This blog is the official source for the updates from the React team. Anything important, including release notes or deprecation notices, will be posted here first. 
+
+You can also follow the [@react.dev](https://bsky.app/profiles/react.js) account on Bluesky, or [@reactjs](https://twitter.com/reactjs) account on Twitter, but you won’t miss anything essential if you only read this blog.
 
 </Intro>
 
 <div className="sm:-mx-5 flex flex-col gap-5 mt-12">
 
+<BlogCard title="Sunsetting Create React App" date="February 13, 2025" url="/blog/2025/02/14/sunsetting-create-react-app">
+
+Today, we’re deprecating Create React App for new apps, and encouraging existing apps to migrate to a framework. We’re also providing docs for when a framework isn’t a good fit for your project, or you prefer to start by building a framework.
+
+</BlogCard>
+
 <BlogCard title="React v19 " date="December 5, 2024" url="/blog/2024/12/05/react-19">
 
 In the React 19 Upgrade Guide, we shared step-by-step instructions for upgrading your app to React 19. In this post, we'll give an overview of the new features in React 19, and how you can adopt them ...

src/content/learn/building-a-react-framework.md

@@ -0,0 +1,127 @@
+---
+title: Building a React Framework
+---
+
+<Intro>
+
+If your app has constraints not well-served by existing frameworks, or you prefer to solve these problems yourself, you can build your own framework.
+
+</Intro>
+
+<Note>
+
+### Consider using an existing framework {/*you-should-probably-use-a-framework*/}
+
+Building a framework is complex and requires extensive expertise across various domains. This complexity is not limited to React — it is a widespread challenge encountered by all UI libraries. Using an existing framework can save significant time and effort by allowing you to focus on building your application. Existing frameworks have tested, robust features and community support.
+
+For a list of recommended frameworks, check out [Creating a React App](/learn/creating-a-react-app).
+
+</Note>
+
+Building a framework is a large undertaking that often requires expertise in many different areas. Understanding your goals and requirements before starting to build your own framework can help guide your development process and save a considerable amount of time.
+
+For example, if you need to build a framework that integrates with a specific system or infrastructure, it's important to understand the features and limitations of those systems. Understanding your constraints can help guide your framework development process. 
+
+If you are building your own framework to learn, using popular tools like Vite and React Router can be a good starting point and let you focus on how to combine different tools to build a framework.
+
+## Step 1: Install a build tool {/*step-1-install-a-build-tool*/}
+
+The first step is to install a build tool like `vite` or `parcel`. 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 vite@latest --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.
+
+<Note>
+
+#### Metro for React Native {/*react-native*/}
+
+If you'd like your framework to support React Native you'll need to use [Metro](https://metrobundler.dev/), the JavaScript bundler for React Native. Metro supports bundling for platforms like iOS and Android, but lacks many features when compared to Vite or Parcel. We recommend starting with Vite or Parcel unless your project requires React Native support.
+
+</Note>
+
+## Step 2: Build your framework {/*step-2-build-your-framework*/}
+
+The build tool you select starts with a client-only, single-page app (SPA). While SPAs can be a good place to start, many SPAs will encounter problems as they grow. Frameworks can provide the scaffolding to solve these problems. Most frameworks will implement routing, code-splitting, different rendering strategies, and data-fetching. These features are interconnected. For example, if you use a router that only works on the client it could prevent you from implementing server-side rendering. The best frameworks provide a cohesive, consistent experience across these features for developers and users.
+
+### Routing {/*routing*/}
+
+Routing determines what 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. Most modern routers use file-based routing. Routing can be integrated with other features like:
+
+* **Rendering strategies** to enable different rendering strategies on different routes, so you can introduce new strategies without having to rewrite your whole app. This can decrease the time it takes for the first byte of content to be loaded ([Time to First Byte](https://web.dev/articles/ttfb)), the first piece of content to be rendered ([First Contentful Paint](https://web.dev/articles/fcp)), and the largest visible content of the app to be rendered ([Largest Contentful Paint](https://web.dev/articles/lcp)).
+* **Data fetching** to enable data fetching before the page loads on a route. This can prevent layout shifts ([Cumulative Layout Shift](https://web.dev/articles/cls)) and decrease the time it takes for the largest visible content of the app to render ([Largest Contentful Paint](https://web.dev/articles/lcp))
+* **Code splitting** to reduce the JavaScript bundle size sent to the client and improve performance on underpowered devices. This can reduce the time it takes for the browser to respond to a user interaction ([First Input Delay](https://web.dev/articles/fid)) and the largest visible content of the app to be rendered ([Largest Contentful Paint](https://web.dev/articles/lcp)).
+
+If you're not sure how to get started with routing, we recommend using [React Router](https://reactrouter.com/start/framework/custom) or [Tanstack Router](https://tanstack.com/router/latest).
+
+### Data-fetching {/*data-fetching*/}
+
+Data-fetching is the process of fetching data from a server or other data source. You need to set up or create a data-fetching library to handle data retrieval from your server and manage the state of that data. You'll also need to handle loading states, error states, and caching data. Data fetching can be integrated with features like:
+
+* **Routing** to enable data fetching to take place before page loads. This can improve how quickly a page loads and becomes visible to users ([Largest Contentful Paint](https://web.dev/lcp)) and reduce time it takes for your app to be interactive ([Time to Interactive](https://web.dev/tti)).
+* **Rendering strategies** to prerender fetched data before it is sent to the client. This can reduce the time it takes for the largest visible content of the app to render ([Largest Contentful Paint](https://web.dev/lcp)).
+
+Integrating routing and data fetching is particularly important to prevent network waterfalls. In a SPA, if you fetch data during a component's initial render, the first data fetch is delayed until all code has loaded and components have finished rendering. This is commonly known as a waterfall: instead of fetching data at the same time as your code is loading, you need to first wait for your code to load before fetching data. To address these waterfalls, your app needs to fetch the data for each route in parallel with sending code to the browser.
+
+Popular data fetching libraries that you can use as a part of your framework include [React Query](https://react-query.tanstack.com/), [SWR](https://swr.vercel.app/), [Apollo](https://www.apollographql.com/docs/react), and [Relay](https://relay.dev/).
+
+### Rendering strategies {/*rendering-strategies*/}
+
+Since the build tool you select only support single page apps (SPAs) you'll need to implement other [rendering patterns](https://www.patterns.dev/vanilla/rendering-patterns) like server-side rendering (SSR), static site generation (SSG), and/or React Server Components (RSC). Even if you don't need these features at first, in the future there may be some routes that would benefit SSR, SSG or RSC.
+
+* **Single-page apps (SPA)** load a single HTML page and dynamically updates the page as the user interacts with the app. SPAs are fast and responsive, but they can have slower initial load times. SPAs are the default architecture for most build tools.
+
+* **Streaming Server-side rendering (SSR)** renders a page on the server and sends the fully rendered page to the client. SSR can improve performance, but it can be more complex to set up and maintain than a single-page app. With the addition of streaming, SSR can be very complex to set up and maintain. See [Vite's SSR guide]( https://vite.dev/guide/ssr).
+
+* **Static site generation (SSG)** generates static HTML files for your app at build time. SSG can improve performance, but it can be more complex to set up and maintain than server-side rendering.
+
+* **React Server Components (RSC)** lets you mix build-time, server-only, and interactive components in a single React tree. RSC can improve performance, but it currently requires deep expertise to set up and maintain. See [Parcel's RSC examples](https://github.com/parcel-bundler/rsc-examples).
+
+Your rendering strategies need to integrate with your router so apps built with your framework can choose the rendering strategy on a per-route level. This will enable different rendering strategies without having to rewrite your whole app. For example, the landing page for your app might benefit from being statically generated (SSG), while a page with a content feed might perform best with server-side rendering. Using the right rendering strategy for the right routes can decrease the time it takes for the first byte of content to be loaded ([Time to First Byte](https://web.dev/articles/ttfb)), the first piece of content to render ([First Contentful Paint](https://web.dev/articles/fcp)), and the largest visible content of the app to render ([Largest Contentful Paint](https://web.dev/articles/lcp)).
+
+### Code-splitting {/*code-splitting*/}
+
+Code-splitting is the process of breaking your app into smaller bundles that can be loaded on demand. An app's code size increases with every new feature and additional dependency. Apps can become slow to load because all of the code for the entire app needs to be sent before it can be used. Caching, reducing features/dependencies, and moving some code to run on the server can help mitigate slow loading but are incomplete solutions that can sacrifice functionality if overused.
+
+Similarly, if you rely on the apps using your framework to split the code, you might encounter situations where loading becomes slower than if no code splitting were happening at all. For example, [lazily loading](/reference/react/lazy) a chart delays sending the code needed to render the chart, splitting the chart code from the rest of the app. [Parcel supports code splitting with React.lazy](https://parceljs.org/recipes/react/#code-splitting). However, if the chart loads its data *after* it has been initially rendered you are now waiting twice. This is a waterfall: rather than fetching the data for the chart and sending the code to render it simultaneously, you must wait for each step to complete one after the other.
+
+Splitting code by route, when integrated with bundling and data fetching, can reduce the initial load time of your app and the time it takes for the largest visible content of the app to render ([Largest Contentful Paint](https://web.dev/articles/lcp)).
+
+### And more... {/*and-more*/}
+
+These are just a few examples of the features a framework will need to consider.
+
+There are many other problems that users need to solve like:
+
+- Accessibility
+- Asset loading
+- Authentication
+- Error handling
+- Mutating data
+- Navigations
+- Nested routes
+- Optimistic updates
+- Caching
+- Progressive enhancement
+- Static site generation
+- Server-side rendering
+
+Many of these problems individually can be difficult as each problem is interconnected with the others and can require deep expertise in problem areas you may not be familiar with. If you don't want to solve these problems on your own, you can [get started with a framework](/learn/creating-a-react-app) that provides these features out of the box. 

src/content/learn/creating-a-react-app.md

@@ -0,0 +1,116 @@
+---
+title: Creating a React App
+---
+
+<Intro>
+
+If you want to build a new app or website with React, we recommend starting with a framework.
+
+</Intro>
+
+## 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*/}
+
+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*/}
+
+**[Next.js's App Router](https://nextjs.org/docs) is a React framework that takes full advantage of React's architecture to enable full-stack React apps.**
+
+<TerminalBlock>
+npx create-next-app@latest
+</TerminalBlock>
+
+Next.js is maintained by [Vercel](https://vercel.com/). You can [deploy a Next.js app](https://nextjs.org/docs/app/building-your-application/deploying) to any Node.js or serverless hosting, or to your own server. Next.js also supports [static export](https://nextjs.org/docs/app/building-your-application/deploying/static-exports) which doesn't require a server. Vercel additionally provides opt-in paid cloud services.
+
+### React Router (v7) {/*react-router-v7*/}
+
+**[React Router](https://reactrouter.com/start/framework/installation) is the most popular routing library for React and can be paired with Vite to create a full-stack React framework**. It emphasizes standard Web APIs and has several [ready to deploy templates](https://github.com/remix-run/react-router-templates) for various JavaScript runtimes and platforms.
+
+To create a new React Router framework project, run:
+
+<TerminalBlock>
+npx create-react-router@latest
+</TerminalBlock>
+
+React Router is maintained by [Shopify](https://www.shopify.com).
+
+### Expo (for native apps) {/*expo*/}
+
+**[Expo](https://expo.dev/) is a React framework that lets you create universal Android, iOS, and web apps with truly native UIs.** It provides an SDK for [React Native](https://reactnative.dev/) that makes the native parts easier to use. To create a new Expo project, run:
+
+<TerminalBlock>
+npx create-expo-app@latest
+</TerminalBlock>
+
+If you're new to Expo, check out the [Expo tutorial](https://docs.expo.dev/tutorial/introduction/).
+
+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*/}
+
+There are other up-and-coming frameworks that are working towards our full stack React vision:
+
+- [TanStack Start (Beta)](https://tanstack.com/): TanStack Start is a full-stack React framework powered by TanStack Router. It provides a full-document SSR, streaming, server functions, bundling, and more using tools like Nitro and Vite.
+- [RedwoodJS](https://redwoodjs.com/): Redwood is a full stack React framework with lots of pre-installed packages and configuration that makes it easy to build full-stack web applications.
+
+<DeepDive>
+
+#### Which features make up the React team’s full-stack architecture vision? {/*which-features-make-up-the-react-teams-full-stack-architecture-vision*/}
+
+Next.js's App Router bundler fully implements the official [React Server Components specification](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md). This lets you mix build-time, server-only, and interactive components in a single React tree.
+
+For example, you can write a server-only React component as an `async` function that reads from a database or from a file. Then you can pass data down from it to your interactive components:
+
+```js
+// This component runs *only* on the server (or during the build).
+async function Talks({ confId }) {
+  // 1. You're on the server, so you can talk to your data layer. API endpoint not required.
+  const talks = await db.Talks.findAll({ confId });
+
+  // 2. Add any amount of rendering logic. It won't make your JavaScript bundle larger.
+  const videos = talks.map(talk => talk.video);
+
+  // 3. Pass the data down to the components that will run in the browser.
+  return <SearchableVideoList videos={videos} />;
+}
+```
+
+Next.js's App Router also integrates [data fetching with Suspense](/blog/2022/03/29/react-v18#suspense-in-data-frameworks). This lets you specify a loading state (like a skeleton placeholder) for different parts of your user interface directly in your React tree:
+
+```js
+<Suspense fallback={<TalksLoading />}>
+  <Talks confId={conf.id} />
+</Suspense>
+```
+
+Server Components and Suspense are React features rather than Next.js features. However, adopting them at the framework level requires buy-in and non-trivial implementation work. At the moment, the Next.js App Router is the most complete implementation. The React team is working with bundler developers to make these features easier to implement in the next generation of frameworks.
+
+</DeepDive>
+
+<Note>
+
+
+#### Do you recommend Vite? {/*do-you-recommend-vite*/}
+
+We provide several Vite-based recommendations.
+
+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.
+
+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).
+
+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>
+
+-----
+
+_If you’re a framework author interested in being included on this page, [please let us know](https://github.com/reactjs/react.dev/issues/new?assignees=&labels=type%3A+framework&projects=&template=3-framework.yml&title=%5BFramework%5D%3A+)._

src/content/learn/installation.md

@@ -8,15 +8,6 @@ React has been designed from the start for gradual adoption. You can use as litt
 
 </Intro>
 
-<YouWillLearn isChapter={true}>
-
-* [How to start a new React project](/learn/start-a-new-react-project)
-* [How to add React to an existing project](/learn/add-react-to-an-existing-project)
-* [How to set up your editor](/learn/editor-setup)
-* [How to install React Developer Tools](/learn/react-developer-tools)
-
-</YouWillLearn>
-
 ## Try React {/*try-react*/}
 
 You don't need to install anything to play with React. Try editing this sandbox!
@@ -39,17 +30,27 @@ You can edit it directly or open it in a new tab by pressing the "Fork" button i
 
 Most pages in the React documentation contain sandboxes like this. Outside of the React documentation, there are many online sandboxes that support React: for example, [CodeSandbox](https://codesandbox.io/s/new), [StackBlitz](https://stackblitz.com/fork/react), or [CodePen.](https://codepen.io/pen?template=QWYVwWN)
 
-### Try React locally {/*try-react-locally*/}
-
 To try React locally on your computer, [download this HTML page.](https://gist.githubusercontent.com/gaearon/0275b1e1518599bbeafcde4722e79ed1/raw/db72dcbf3384ee1708c4a07d3be79860db04bff0/example.html) Open it in your editor and in your browser!
 
-## Start a new React project {/*start-a-new-react-project*/}
+## Creating a React App {/*creating-a-react-app*/}
+
+If you want to start a new React app, you can [create a React app](/learn/creating-a-react-app) using a recommended framework.
 
-If you want to build an app or a website fully with React, [start a new React project.](/learn/start-a-new-react-project)
+## Build a React Framework {/*build-a-react-framework*/}
+
+If a framework is not a good fit for your project, or you prefer to start by building your own framework, you can [build your own React framework](/learn/building-a-react-framework).
 
 ## Add React to an existing project {/*add-react-to-an-existing-project*/}
 
-If want to try using React in your existing app or a website, [add React to an existing project.](/learn/add-react-to-an-existing-project)
+If want to try using React in your existing app or a website, you can [add React to an existing project.](/learn/add-react-to-an-existing-project)
+
+## Deprecated Options {/*deprecated-options*/}
+
+### Create React App (Deprecated) {/*create-react-app-deprecated*/}
+
+Create React App is a deprecated tool, previously recommended for creating new React apps. If you want to start a new React app, you can [create a React app](/learn/creat-a-react-app) using a recommended framework. 
+
+For more information, see [Sunsetting Create React App](/blog/2025/02/14/sunsetting-create-react-app).
 
 ## Next steps {/*next-steps*/}
 

src/content/learn/setup.md

@@ -0,0 +1,32 @@
+---
+title: Setup
+---
+<Intro>
+
+React integrates with tools like editors, TypeScript, browser extensions, and compliers. This section will help you get your environment set up.
+
+</Intro>
+
+## Editor Setup {/*editor-setup*/}
+
+See our [recommended editors](/learn/editor-setup) and learn how to set them up to work with React.
+
+## Using TypeScript {/*using-typescript*/}
+
+TypeScript is a popular way to add type definitions to JavaScript codebases. [Learn how to integrate TypeScript into your React projects](/learn/typescript).
+
+## React Developer Tools {/*react-developer-tools*/}
+
+React Developer Tools is a browser extension that can inspect React components, edit props and state, and identify performance problems. Learn how to install it [here](learn/react-developer-tools).
+
+## React Compiler {/*react-compiler*/}
+
+React Compiler is a tool that automatically optimizes your React app. [Learn more](/learn/react-compiler).
+
+## Start a React Project from scratch {/*start-a-react-project-from-scratch*/}
+
+If you want to build your own framework, you can [start a React project from scratch](/learn/start-a-react-project-from-scratch).
+
+## Next steps {/*next-steps*/}
+
+Head to the [Quick Start](/learn) guide for a tour of the most important React concepts you will encounter every day.

src/sidebarLearn.json

@@ -25,13 +25,23 @@
       "path": "/learn/installation",
       "routes": [
         {
-          "title": "Start a New React Project",
-          "path": "/learn/start-a-new-react-project"
+          "title": "Creating a React App",
+          "path": "/learn/creating-a-react-app"
+        },
+        {
+          "title": "Building a React Framework",
+          "path": "/learn/building-a-react-framework"
         },
         {
           "title": "Add React to an Existing Project",
           "path": "/learn/add-react-to-an-existing-project"
-        },
+        }
+      ]
+    },
+    {
+      "title": "Setup",
+      "path": "/learn/setup",
+      "routes": [
         {
           "title": "Editor Setup",
           "path": "/learn/editor-setup"

tsconfig.json

@@ -22,12 +22,18 @@
     "isolatedModules": true,
     "jsx": "preserve",
     "baseUrl": "src",
-    "incremental": true
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
   },
   "include": [
     "next-env.d.ts",
     "src/**/*.ts",
-    "src/**/*.tsx"
+    "src/**/*.tsx",
+    ".next/types/**/*.ts"
   ],
   "exclude": [
     "node_modules"

vercel.json

@@ -164,6 +164,11 @@
       "destination": "https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html",
       "permanent": false
     },
+    {
+      "source": "/link/cra",
+      "destination": "/blog/2025/02/14/sunsetting-create-react-app",
+      "permanent": false
+    },
     {
       "source": "/warnings/version-mismatch",
       "destination": "/warnings/invalid-hook-call-warning#mismatching-versions-of-react-and-react-dom",
@@ -224,6 +229,11 @@
       "destination": "https://18.react.dev/reference/react-dom/server/renderToNodeStream",
       "permanent": true
     },
+    {
+      "source": "/learn/start-a-new-react-project",
+      "destination": "/learn/creating-a-react-app",
+      "permanent": true
+    },
     {
       "source": "/blog/2024/04/25/react-19",
       "destination": "/blog/2024/12/05/react-19",