create-react-app is a zombie application
create-react-app hasn't been in the official documentation for over a year, but that doesn't stop a constant flood of new developers from trying to use it.
We’ve talked before about how companies rely on donated labor for open-source software. But the donated labor isn’t always unpaid; sometimes people make money by writing technical articles explaining a specific technology. If someone builds a new popular piece of software, roughly the following will happen:
The community experiments with the library. People find nice or clever ways to use the library. They document it in social media posts, blogs, YouTube videos, etc.
The tips and tricks begin to coalesce into conventional wisdom.
Content farm websites begin to collect and publish all of the conventional wisdom. Soon they will be published everywhere: blog posts, video, infographics, PDF cheat sheets, etc.
The content farms use SEO keyword research to discover new articles that they should write, ensuring that they appear in the search results of more and more topics.
Eventually, every web search about the technology is dominated by the content farms.
But what happens if there’s a major paradigm shift and all of the third-party content is now out of date? This creates a split-brain situation. The right way is buried, buried by all of the content farms that appear in search. Your users — especially new ones — are confused because they find the out-of-date resources and don’t understand the historical context.
create-react-app has been going through this for years now. This is a program that generates React applications. React is currently the most-popular frontend UI library for building web applications. create-react-app is necessary because React’s build step is complex. React is written with a JavaScript language extension called JSX that allows developers to mix HTML and JavaScript when building dynamic user interfaces. Browsers don’t understand JSX, so the React build step needs to additionally convert the JSX into JavaScript before it can successfully run in an application.
At the moment, create-react-app is basically broken and deprecated. It has conflicts with React 19 — which is the current version of React — and it is no longer referenced in the official React documentation as a proper way to create a new React app. And yet, it trudges on like a zombie, not quite deprecated, but not fit for production use. How did we get here?
When React was first introduced, libraries were written in pure JavaScript. So it was jarring to have an additional transpilation step that required installing Babel.js and adding and configuring the correct plugins. To make this easier, the React team made create-react-app that just handled everything for you.
Dan Abramov comment on Github issue “Replace Create React App recommendation with Vite”
Before Create React App, you had to install a bunch of tools and wire them up together, provide the right presets to use JSX, configure them differently for development and production environments, provide the right settings for asset caching, configure the linter, and so on. This was very tricky to do correctly. People coped with this by creating and sharing "boilerplate" repositories that you could clone. However, that created a different problem: once you cloned the boilerplate and adjusted it for your project, it was hard to pull updates. Your project setup would get stale, and you'd either give up on updating or spend a lot of effort getting all tools to work together again. In a fast-moving ecosystem, this was very difficult.
Create React App solved this by combining several tools under one package, choosing a reasonable default configuration, and then papering over all the little incompatibilities between the tools. Now, if you wanted to start a new project with React, there was a single clear recommended way to do that!
If you’re a software engineer that has never done modern web development, a perfectly reasonable — but completely misguided — thought would be, “Most computer languages aren’t like this. Why is this so hard? Why can’t they simply create JavaScript files that import React and use it? What does it matter what create-react-app does?” The core problem is that JavaScript isn’t real.
Web browsers allow users to view web pages. Web pages run scripts that read and modify the content of the page. ECMAScript — the official name for JavaScript — is the only real option for doing this for most use cases.
Originally, JavaScript was an underpowered language that didn’t even have an official way to declare that one file/module/whatever depended on another. These gaps were always filled with libraries, or handled by the tool that bundled all of your JavaScript files together. Accordingly, critical functionality has always been implemented using build systems and libraries.
This has become more important over time. JSX allows you to combine HTML and JavaScript. Newer plugins allow you to do things like import CSS files into JavaScript and reference the CSS rules directly, and under the hood the compiler just produces separate CSS and JavaScript files, and checks that all of the referenced CSS rules actually exist. Plugins can allow you to use other languages like TypeScript, make your program hot swappable for development1, create efficient versions for the production app that you serve users, etc.
So the fact remains: JavaScript isn’t real. You can’t look at a JavaScript source and know what the output will be without also knowing what plugins it will be compiled with, and what the target language is. If your JavaScript includes CSS files, is that a syntax error or just a normal part of your build system? Well, it depends on whether you have a plugin that can process CSS. This is completely unlike any other programming language that I’ve worked in.
So yeah, that’s how we ended up with create-react-app. It is built to solve the not-realness of JavaScript. With a single command, it produces an entire working React app that has development and production versions, and gives you a lot of nice-to-have features. But over time, it was surpassed by more advanced tooling and it could never compete with fully-fledged frameworks. create-react-app is now effectively deprecated. The React team removed references to it from the official documentation. That should have been the end of it, right?
Well, unfortunately not. If you scroll down in that issue, you see that people are still reporting create-react-app failures, and finally porting their create-react-app tooling to more modern approaches. If you check out /r/reactjs, you can find plenty of examples of people trying to use create-react-app and running into errors.
I wish they’d officially shut CRA down. It’s way too common a trap, even for intermediate devs who’ve never had to set up a new project from scratch. It’s all too likely to show up when someone with no prior knowledge inevitably Googles “how to create a react app,” and there are no immediate signs you’re making a mistake if you find yourself on any of CRA’s official documentation pages or its repo.
This is easy to verify yourself. If you simply search Google for the phrase, “how to create a react app,” several of the above-the-fold responses include the command that explains how to run create-react-app.
The biggest tragedy is that it’s not really anybody’s fault at the moment. React removed it from their documentation. It’s not technically deprecated, so there’s no reason for the content farm sites to take it down. The content farm sites are popular and do provide a helpful resource for using create-react-app, so why shouldn’t Google include them in their search results? The best thing that could happen seems to be the React team officially deprecating the application altogether, so that developers can finally move on to more important things.
As a developer, there is a teaching moment here: when you’re learning a new technology, look at the official documentation before trying out unofficial documentation sources. A “getting started” tutorial is bog standard these days. Just go through it, kick the tires, change something and recompile. You’ll save yourself a lot of frustration.
Hot swapping is when you press “Save” in your editor, and the webpage you have open locally automatically reloads.