Repository: create-react-app
Issue: Umbrella: CRA breaks with React 19, and CRA needs deprecation notices
Labels: needs triage,issue: bug report

Per request from @rickhanlonii :

## Background / Primary Problem

Starting with the release of React 19, users running `create-react-app my-app` began experiencing hard errors from NPM during project setup.

This is due to a combination of multiple factors:

- CRA has always installed the latest available version of React by default, and that version is not listed in the template packages
- The default templates _do_ use React Testing Library
- The default templates currently use `@testing-library/react@13.0`. However, that version has an expected peer dependency of `react@18`. That means that installing React 19 causes a peer dependency mismatch
- NPM has a notoriously inflexible stance towards peer dep mismatches, and immediately throws an error when it hits a mismatch, and NPM is the default package manager used for CRA project setup

This causes a perfect storm of incompatibility. CRA creates a new project, adds React 19, tries to use NPM to install the packages, and NPM errors due to the peer dep mismatch with RTL.

### Solution

**This can be fixed by merging a PR that updates the versions of RTL listed in the default templates, to the latest RTL releases that support React 19**.  That will eliminate the peer dep mismatch and should allow project creation to succeed without errors.

There's a couple RTL template fix PRs up already.  This one looks like it should work:

- https://github.com/facebook/create-react-app/pull/13738

#### Testing Template Changes

I checked the CRA CLI logic, and you can specify templates with an NPM version. So, we ought to be able to publish `cra-template@alpha` or some other similar tag to NPM, then do a CRA install with `create-react-app my-app --template cra-template@alpha` to verify it works.

## Additional Problem: Users Still Try to Use Create React App, Without Knowing It's Deprecated

### CRA Is Still Referenced in Many Tutorials

The peer dep mismatch problem is easily fixable by itself, but it's also exacerbated by the fact that CRA has been _officially_ unmaintained for 2+ years, and in practice for longer than that.  Additionally, while the broader React community has known for years that "CRA is  deprecated, don't use it", there's a very long tail of existing tutorials and articles that tell readers to start a new project by using CRA.  Additionally, the old React docs did say "use CRA", and technically that page is even still up:

- https://legacy.reactjs.org/docs/create-a-new-react-app.html#recommended-toolchains

> The React team primarily recommends these solutions:
> - If you’re learning React or creating a new [single-page](https://legacy.reactjs.org/docs/glossary.html#single-page-application) app, use [Create React App](https://legacy.reactjs.org/docs/create-a-new-react-app.html#create-react-app).

In fact, if I do a search for `new react app`, the top hit is that legacy docs page, and the third hit is the CRA docs:

![Image](https://github.com/user-attachments/assets/15c8951e-8a2f-4ded-bdeb-e20544255f98)

### Beginners Are Most Likely to Try Using CRA

The most likely type of user to run into this problem is a beginner who's just getting started.  While I don't have hard numbers how many people _are_ running into this, I've seen numerous reports of this error across Reddit, the CRA and React repos, and Reactiflux.  Some examples:

- https://www.reddit.com/r/reactjs/comments/1i49yo9/whats_going_on_with_create_react_app_errors_and/
- https://www.reddit.com/r/reactjs/comments/1hvw86m/wtf_is_up_with_basic_install_shouldnt_be_this_hard/
- https://www.reddit.com/r/reactjs/comments/1hsez1y/help_for_a_complete_noobnot_able_to_install_react/
- https://www.reddit.com/r/reactjs/comments/1hp2hcj/create_a_new_react_app_version_error/

and from the current CRA issues:

![Image](https://github.com/user-attachments/assets/c11eb8b0-2731-4e46-89fc-f4fa6a141240)

Given that, there's clearly a significant number of users being affected by these errors, enough that it's worth both fixing the immediate errors, and giving them a longer-term migration path or directions away from CRA.

### The CRA Docs, README, and CLI Do Not Declare It As Deprecated

While the React community as a whole knows CRA is deprecated, that is not actually stated anywhere in the CRA docs or README.  There's nothing to tell a user "don't use CRA", or any pointers to the ["Start a New React Project" page on React.dev](https://react.dev/learn/start-a-new-react-project).

Similarly, the CRA CLI does not print any deprecation warnings.

So, there's nothing to even indicate to a user that "this is the wrong and outdated approach, don't use this, there are better tools available".

### Immediate Solution

- **The CRA CLI should be updated to print a loud and clear "CRA is deprecated, see the React docs 'Start a Project' page for alternatives" message** (but, ideally, _not_ throw an error for now)
- **The CRA docs and README should be updated to state it's deprecated**

There's a PR up to update the CLI with a deprecation message:

- https://github.com/facebook/create-react-app/pull/17003

As a longer-term step, it's worth seriously considering if the CRA repo should be archived until there's any decision or forward motion on future changes such as turning CRA into a "meta-launcher" for creating a project.


## Related: The React Docs Do Not List a Direct Equivalent to CRA for New Projects

(I know @rickhanlonii directly disagrees with me on this. Writing it up anyway as a description of why I feel this is relevant.  **This should not block the work to fix the _actual_ problems described above**, but this topic does tie in to how the deprecation notices should be handled and how we want to direct users to proceed if they move away from CRA.)

Per above, the legacy React docs recommended CRA for "learning and Single-Page Apps".

The current React docs do not mention CRA.  Instead, the ["Start a New React Project" page](https://react.dev/learn/start-a-new-react-project) heavily directs users to use "a production-grade React framework" (currently listing Next, Remix, Gatsby, and Expo), with the stance that it's better to use a purpose-built framework rather than cobbling one together yourself with several libraries.

While all of those frameworks can be used to create an SPA with client-side behavior in general, they also all (intentionally) add a lot of additional opinions and complexity.  Whether that's good or bad, none of them are a direct 1:1 equivalent of the kind of basic client-only SPA architecture that CRA created.

Client-only SPAs have historically been an extremely common way to use React.  They're also simpler, in that there's fewer moving pieces to understand, and thus more suitable for beginners.

Today, Vite is by far the best tool for creating a new basic React client SPA project.  CRA projects can be straightforwardly migrated to Vite, Vite comes with basic React templates built into `create-vite`, and Vite also forms the basis for some React-based frameworks already.  (RSBuild is also an option for migrating away from CRA projects, but it's admittedly much newer and less mature.)

Vite is _briefly_ mentioned in a couple places in the docs, but those mentions are buried and intentionally not given the same weight as the "framework" options:

- https://react.dev/learn/start-a-new-react-project#can-i-use-react-without-a-framework ( buried down inside of an expandable details section for "Can I Use React Without a Framework"): 
    > If your app has unusual constraints not served well by these frameworks, or you prefer to solve these problems yourself, you can roll your own custom setup with React. Grab react and react-dom from npm, set up your custom build process with a bundler like [Vite](https://vitejs.dev/) or [Parcel](https://parceljs.org/), and add other tools as you need them for routing, static generation or server-side rendering, and more.
- https://react.dev/learn/add-react-to-an-existing-project#step-1-set-up-a-modular-javascript-environment :
    > If your app doesn’t have an existing setup for compiling JavaScript modules, set it up with [Vite](https://vitejs.dev/). The Vite community maintains [many integrations with backend frameworks](https://github.com/vitejs/awesome-vite#integrations-with-backends), including Rails, Django, and Laravel. If your backend framework is not listed, [follow this guide](https://vitejs.dev/guide/backend-integration.html) to manually integrate Vite builds with your backend.

Neither of those meaningfully presents users with a direct path away from CRA, nor do they match the widescale usage of Vite as a common tool for client-side SPAs in the React ecosystem.

### Ideal Solution

Given that, my ideal magic-wand wishlist of steps would be:

- The "Start a New React Project" page would add a section explicitly listing "client-only / SPA" apps (whatever the desired term is) as a valid category of React app
- That section would specifically recommend Vite as the best tool for building client-only / "DIY-framework" style React apps
- The CRA docs would potentially be moved to a `legacy.create-react-app.dev` subdomain, and replaced with a landing page directing to some combo of Vite for new projects, and pages for migrating existing projects to Vite, Next, Remix, etc

That way, there's a direct replacement listed for users who want to create this style of app, and beginners running into those deprecation notices are given a path to hopefully move forward with whatever tutorial or learning process they're on without having to deal with additional complexity.

<div id="vite-recommendation-wording"></div>

#### Vite Recommendation Wording

For the "Start a New React Project" page, I would specifically like to see a section added with roughly this phrasing:

> ## Single Page Applications
> 
> 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.
> 
> The most common build tool for this use case is Vite.  Since Vite projects do not have opinions, we recommend starting with one of these templates that includes React-based routing libraries with data loading functionality built in:
>   
> - Vite + React Router template
> - Vite + TanStack Router template
> 
> Alternately, you can start from the basic Vite React template and choose your own libraries as needed.

I'm happy to see the exact wording tweaked, but the key points are:

- List Vite specifically as a valid option for starting a React project
- List some of the use cases why it might be a good choice
- Acknowledge that there are many ways to use React, and frameworks are not "one size fits all"

The React team has indicated in the last couple days that "Vite + a data loading router" seem to fit their definition of a suitable "framework", so I'm hopeful that this phrasing would be acceptable.