Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
markerikson opened this issue Jan 25, 2025 · 22 comments
Closed

Comments

@markerikson
Copy link

markerikson commented Jan 25, 2025

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:

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:

The React team primarily recommends these solutions:

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

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:

and from the current CRA issues:

Image

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:

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:

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
Copy link

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
Copy link

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
Copy link

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
Copy link

t3dotgg commented Jan 26, 2025

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
Copy link
Member

rickhanlonii commented Jan 28, 2025

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:

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
Copy link
Author

Awesome, thank you!

@shineum

This comment has been minimized.

@nicolo-ribaudo
Copy link

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
Copy link
Member

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

@rickhanlonii
Copy link
Member

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:

@nicolo-ribaudo
Copy link

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

@rickhanlonii
Copy link
Member

@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.

@hichemfantar
Copy link

This is an opportunity to finally add vite properly in the react docs
reactjs/react.dev#7416

@tushgaurav
Copy link

I was facing some difficulties and errors setting up a old project which used CRA, a few days back. Thanks for the solution.

@nickserv
Copy link
Contributor

nickserv commented Jan 31, 2025

@rickhanlonii Please deprecate the npm package too.

  • It tells package managers and dependent packages that this package is deprecated programatically.
  • It shows a warning at install time, not just run time.
  • The warning can be in all old versions, not just the ones with these patches.
  • It's reversible, so the package can still be used for other purposes in the future (like the previously discussed launcher CLI).
  • It lets you hide npm search results without unpublishing.

Source: https://docs.npmjs.com/deprecating-and-undeprecating-packages-or-package-versions

@rickhanlonii
Copy link
Member

@nickserv eventually it will be deprecated on NPM, but I don't think it makes sense to do it immediately.

For a global script, there shouldn't be many/any dependents. You also don't want it to just warn at install time, you want it to warn whenever you try to install a new project. But most importantly, it would be really confusing to remove such a popular package from npm search.

Just imagine how many people would go to npm the day after we deprecated it and search for create-react-app and not find it. So I think it's a lot better experience to keep it in search so folks can still find it and see the deprecation links with explanations.

Deprecating and entire package on npm is basically deleting it. We're not deleting create-react-app yet.

Deprecating a package is an alternative to deleting a package if your package does not meet the unpublishing requirements.

@nickserv
Copy link
Contributor

You also don't want it to just warn at install time, you want it to warn whenever you try to install a new project.

I wasn't suggesting it as a replacement for the current logs, but maybe a deprecation message for react-scripts could be helpful eventually.

But most importantly, it would be really confusing to remove such a popular package from npm search.

Hm, wasn't aware that deprecation removes results from npm search. Though I'd expect most users are coming from the docs or a tutorial with an npx or npm create style command, not trying to find documentation directly from npm when they know the name of the package and can use a different search engine. Also FWIW the current readme just links to docs. Searching for Create React App on npm doesn't tell you what it is, but the project's general search engine metadata does.

Alternatively, maybe only old releases could be deprecated so the latest readme would still be indexed in search, and there wouldn't be as many duplicate warnings (install time from npm deprecate and then runtime from #17003).

Deprecating and entire package on npm is basically deleting it.

I disagree, I see it as more of a way of signaling new usage isn't recommended (similarly to deprecation warnings in TypeScript types or reference documentation), though the search issue is a good point.

@isEkraZero

This comment has been minimized.

@rickhanlonii
Copy link
Member

Quick update: I'm still doing some testing, and we are also working on some docs to explain the deprecation and how to migrate so can include links in the warning and deprecation banner.

We plan on having that out next week, and we'll publish the new version then.

cc @mattcarrollcode

@rickhanlonii
Copy link
Member

Update: we've published a blog post announcing that we're Sunsetting Create React App, and have merged #17008 to add a deprecation banner to create-react-app.dev and remove CRA from search indexing.

To help address the docs concerns, we've also updated the Start a React Project guide (now titled Creating a React App) and published new docs for building a React framework starting with a build tool like Vite or Parcel.

As of this point, it's officially deprecated. I'm working to publish the new version of CRA with the deprecation warning and React 19 support now.

@rickhanlonii
Copy link
Member

Update: unfortunately I don't have access to cra-template and cra-template-typescript, which are needed to publish the fix for React 19. I've reached out to @iansu for an invite and will test and publish once I have access.

@rickhanlonii
Copy link
Member

Update: create-react-app@5.1.0 has been published (thanks @iansu for the assist)!

I believe all the items has been addressed, so going to close this but let me know if I missed anything!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests