Umbrella: CRA breaks with React 19, and CRA needs deprecation notices

[markerikson]

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:

• fix: upgrade RTL version to avoid peer-deps mismatch #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 app, use 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:

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:

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.

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:

• Deprecate Create React App officially by changing the README, and adding a message on init #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 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 or Parcel, 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. The Vite community maintains many integrations with backend frameworks, including Rails, Django, and Laravel. If your backend framework is not listed, follow this guide 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.

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.

[DogPawHat]

On the point about beginners starting with CRA, I've just done a bunch of tests with few LLM's (Prompting "Can you recommend the best way to create a react app" into ChatGPT 4o, 4o mini, Claude 3.5 Haiku and Sonnet, DeepSeek v3 and r1), and with the exception of r1, they all have CRA as the top answer. Haiku, which is now the only free model from Anthropic, even lists it as the "Official Method"

Pitfalls of llm-driven research aside, I'm pretty sure this problem is downstream of the prominence of the old legacy docs in the general database as shown with the new react app Google search. I am far from an expert on how to correct llm training, but I assume it would overlap with improving the SEO of the newer docs.

(R1's response and its chain of though is quite intresting as you can see it realize CRA is unmaintained and it eventually recommends Vite. I've put the whole thing with the chain of thought in this gist https://gist.github.com/DogPawHat/f0123d763e87d93413c91a0365598aea)

[DogPawHat]

On migrating away from CRA, I did a migration from CRA to Vite about 2 years ago which was simple-ish (and was inspired by this Theo vid https://www.youtube.com/watch?v=M4CLvtCS2YU). I had to change some syntax, rename all the .js files to .jsx, and when I deployed it to Vercel I changed the preset to Vite as well which broke it because Vercel's CRA preset assumes your using React Router or something similar and has the rewrite to handle direct links. But that's miles better then ejecting into whatever Webpack chaos is hiding under the hood.

Regardless of Vite's status as a first class citizen for "Getting Started", it's been the most obvious path for migrations away from CRA for over three years at this point. I'm giving a +1 to having pages on the cra docs to plan out migration stories (including the eject to webpack story since there might be a path to rspack/turbopack there)

[snewell92]

At my last job, migrated from CRA to Vite just last year. The power of defaults! Luckily there was more than one of us who wanted something better for our immediate DX and prod build.

Imo, most SPA use cases for SMBs and Enterprises, where the API is a separate ecosystem (ie .NET / Python / Ruby/ Go), and there is no SSR by design, are best started and served by starting out with vite. Especially for teams relatively new to React, it's a great starting place and experience. There is a clear pipeline in my mind from vite to something more susbtantial (astro/remix/next) as needed. But adhereing to YAGNI will help cement React for the next 50 yeara imo.

Let's not sell React users a framework, but rather showcase solutions.

[t3dotgg]

As an educator in the space, CRA's lack of deprecation notices are a constant stumbling block for new developers and inexperienced React users. It's an unnecessary harm to the entire ecosystem and it's SO easy to mitigate.

I'm sorry guys. There's really no excuse. It's time to mark this project as deprecated

[rickhanlonii]

Update

Thanks for filing the umbrella issue @markerikson. We're going to fix CRA for 19 and deprecate it, as suggested.

I looked at the two PRs:

• [blocked] Fix the template: fix: upgrade RTL version to avoid peer-deps mismatch #13738
  • I merged in the types from update rtl version to 16.1.0 and updated types/react to 19 #13725
  • I added some more fixed, but tests are still failing. I need to figure out a fix.
• Deprecation warnings: Deprecate Create React App officially by changing the README, and adding a message on init #17003
  • This is ready to merge, waiting for the above fix to land first.

Once both of these land we can publish a new version. As a followup we'll also want to kill/redirect the links with high SEO rank to the correct sources. (edit: #17008)

[markerikson]

Awesome, thank you!

[shineum]

As others already mentioned, create app command is changed.
https://react.dev/learn/start-a-new-react-project

This is a tip for someone who still wants to use create-react-app command.

Assuming that working directory is "/Projects/react".

1. Create "temp" folder at "/Projects/react"
2. Install "cra-template" module at temp folder
   
3. Edit node_modules/cra-template/template.json file (library versions)
   
4. Create react app with this command at "/Projects/react"

npx create-react-app my-app --template file:./temp/node_modules/cra-template

[nicolo-ribaudo]

Hey, can we also get #12364 released? Right now Babel had to keep that package as an unused dependency just because CRA forgot to include it in its dependencies list.

[rickhanlonii]

@nicolo-ribaudo that's merged so it will go out with the next release.

[rickhanlonii]

PRs merged, just need to test and publish. Will wait until tomorrow to do that.

I also drafted a updates to the docs to address the SEO issues:

• Add deprecation to website #17008
• Make certain pages always redirect to new site reactjs/legacy.reactjs.org#6

[nicolo-ribaudo]

Q: do you plan to only deprecate this in the docs, or also to npm deprecate it?

[rickhanlonii]

@nicolo-ribaudo for now I'm only planning to deprecate with a message that prints when you run it, and a deprecate it in the docs/readme. Eventually we will probably deprecate the package itself.