Upgrades and deprecations
Create React App to Vite: Migration Steps and the Gotchas
In short
To migrate Create React App to Vite, swap react-scripts for Vite and its React plugin, move index.html to the project root, and rename every REACT_APP_ variable. The build usually comes back quickly. What breaks later is quieter: process.env reads, SVG component imports, the catch-all dev proxy and Jest mocks, none of which Vite copies.
What did the React team say about Create React App, and when?
The deprecation is dated. React's blog post of 14 February 2025, titled Sunsetting Create React App, deprecates it for new apps. Teams with an existing app are told to adopt a framework, or to switch to a bundler and name Vite, Parcel and Rsbuild as the options. The stated reason is blunt: the project has no active maintainers.
From that day a fresh install prints a one-time warning that create-react-app is deprecated and points to react.dev/link/cra. The post says the tool keeps working in maintenance mode and that a new release was published so it works with React 19.
The registry agrees. The create-react-app package's latest version is 5.1.0, published on 15 February 2025 (UTC), while react-scripts, the package your app actually runs, still has 5.0.1 as its latest tag. The GitHub README now opens with a Deprecated caution that calls the project in long-term stasis and advises against starting production apps on it.
If an install already fails rather than warns, this fix page covers that case.
Does React point you to Vite, or to a framework?
A framework comes first. The sunset post recommends starting new React apps with one and gives a rule of thumb: if the app needs routing, a framework will probably serve it better. It lists migration guides for Next.js, React Router and Expo.
Vite is the build-tool route, for apps with unusual constraints or teams that want to own the setup. React's Build a React App from Scratch page lists Vite first and notes that React Router, one of its recommended frameworks, already runs on Vite.
One detail matters when you go looking for instructions. The link the sunset post labels as the Vite Create React App migration guide points to a personal blog, not to vite.dev. None of the vite.dev pages I read for this post mention Create React App. So the mapping below is assembled from Vite's own reference pages and the old CRA docs, which is the join neither side publishes.
How do you migrate Create React App to Vite, step by step?
This is the order I would follow, reading each step from the docs listed under Sources. Commit before you start so every step can be diffed.
- Check Node first. The Vite getting-started page says Vite needs Node.js 20.19+ or 22.12+, and some templates want newer.
- Remove react-scripts and add
vitewith@vitejs/plugin-react(or@vitejs/plugin-react-swc) as dev dependencies, then register the plugin in avite.configfile. - Move
index.htmlout ofpublicto the project root. Vite treats that file as source and as the entry point, so it needs a<script type="module" src="...">tag pointing at your entry file. - Replace the scripts. Vite's scaffold uses
vitefor the dev server,vite buildfor production andvite previewto check the build locally. - Rename files whose components contain JSX if they end in
.js. The features page documents JSX support for.jsxand.tsxfiles. - Decide on two defaults. Vite writes the build to
dist, so setbuild.outDirif your host expectsbuild. The dev server listens on 5173, not the 3000 the CRA README describes, andserver.portchanges it.
Checked against: source 2, source 5, source 8, source 10, source 11
Which CRA habits have no one-to-one Vite equivalent?
Each row pairs what the CRA user guide documents with what the Vite reference says. The last column is the change to make, not a library recommendation.
| CRA habit | How CRA documented it | What Vite documents | What to change |
|---|---|---|---|
| `REACT_APP_` prefix | Only `REACT_APP_` variables, plus `NODE_ENV` and `PUBLIC_URL`, reach the code | Only `VITE_` variables are exposed; `envPrefix` changes the prefix | Rename, or set `envPrefix: 'REACT_APP_'` |
| `process.env.X` in browser code | Replaced with the value at build time | Values live on `import.meta.env`; the mode is `import.meta.env.MODE`, with `DEV` and `PROD` booleans | Rewrite reads; use `define` only for a named unprefixed value |
| `%PUBLIC_URL%` in index.html | Built-in variable | `%NAME%` works only for keys on `import.meta.env`; unknown ones stay in the HTML as typed | Delete it or use `%BASE_URL%` |
| `import { ReactComponent } from './logo.svg'` | Named import returns a React component | An SVG import is an asset URL; `?raw` and `?url` change that; the typings tip shows a component only as a type override | Add an SVG plugin or switch to `<img>` |
| `"proxy"` in package.json, or `src/setupProxy.js` | Any request that is not a static asset and not asking for text/html falls back to the API | `server.proxy` matches only the path prefixes (or `^` regexes) you list | List every API prefix explicitly |
| `react-scripts test` (Jest) | Bundled with the scripts package | Vitest offers a Jest-compatible API with documented differences | Move to Vitest or keep Jest with its own config |
Checked against: source 6, source 7, source 8, source 9, source 10, source 12, source 13, source 14, source 15
What breaks after the first green build?
Environment values are where the quiet failures live. A missing variable becomes undefined in JavaScript but stays as literal text in HTML. Every value arrives as a string, so a VITE_ flag set to false is still truthy. Vite also refuses an empty envPrefix because that would expose every variable, and it warns that anything with the prefix ends up inside the bundle. See this fix page if process is undefined at runtime, and this one for the CRA side.
Tests are the second trap. Vitest's Jest migration page says globals such as describe are off by default, and with them off Testing Library will not clean up the DOM automatically. A vi.mock factory has to return an object with each export named, __mocks__ folders load only when vi.mock is called, and jest.requireActual becomes vi.importActual. If a suite fails on import.meta.env, this page covers it.
The proxy is the third. Under CRA a request to any unknown path fell through to your API. Under Vite, a path you did not list hits the dev server instead, which shows up as HTML where JSON was expected. This page covers that symptom, and this one the SVG import.
What else do people ask?
Is Create React App still safe to run in production?
React says it keeps working in maintenance mode with no active maintainers, and the README advises against starting production apps on it. Existing apps run; the risk is that nothing new arrives for them.
Can I keep my REACT_APP_ variable names?
Yes. Vite's <code>envPrefix</code> option accepts a string or a list of prefixes, so setting it to <code>REACT_APP_</code> keeps the names. You still read them from <code>import.meta.env</code>, not <code>process.env</code>.
Sources
- react.dev blog, Sunsetting Create React App (14 February 2025), fetched 2026-11-20
- Create React App README, deprecation notice, fetched 2026-11-20
- npm registry, create-react-app and react-scripts versions and publish dates, fetched 2026-11-20
- react.dev, Build a React App from Scratch, fetched 2026-11-20
- Vite guide, Getting Started (Node versions, index.html, scripts), fetched 2026-11-20
- Vite guide, Env Variables and Modes, fetched 2026-11-20
- Vite config, shared options (envPrefix, define), fetched 2026-11-20
- Vite guide, Features (JSX, client types, React plugins), fetched 2026-11-20
- Vite guide, Static Asset Handling, fetched 2026-11-20
- Vite config, server options (port, proxy), fetched 2026-11-20
- Vite config, build options (outDir), fetched 2026-11-20
- Create React App docs, Adding Custom Environment Variables, fetched 2026-11-20
- Create React App docs, Adding Images, Fonts, and Files (SVG components), fetched 2026-11-20
- Create React App docs, Proxying API Requests in Development, fetched 2026-11-20
- Vitest guide, Migrating from Jest, fetched 2026-11-20
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. This page joins documents I fetched on 20 Nov 2026 (react.dev, the Create React App README and docs, the npm registry, vite.dev and vitest.dev). I did not migrate an app for it. It does not cover ejected CRA configs, custom webpack setups, TypeScript path aliases or moving to a framework. Found a mistake? Tell me.