Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4133 pages

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.

Checked against: source 1, source 2, source 3

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.

Checked against: source 1, source 4, source 5

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 vite with @vitejs/plugin-react (or @vitejs/plugin-react-swc) as dev dependencies, then register the plugin in a vite.config file.
  • Move index.html out of public to 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 vite for the dev server, vite build for production and vite preview to check the build locally.
  • Rename files whose components contain JSX if they end in .js. The features page documents JSX support for .jsx and .tsx files.
  • Decide on two defaults. Vite writes the build to dist, so set build.outDir if your host expects build. The dev server listens on 5173, not the 3000 the CRA README describes, and server.port changes 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 habitHow CRA documented itWhat Vite documentsWhat to change
`REACT_APP_` prefixOnly `REACT_APP_` variables, plus `NODE_ENV` and `PUBLIC_URL`, reach the codeOnly `VITE_` variables are exposed; `envPrefix` changes the prefixRename, or set `envPrefix: 'REACT_APP_'`
`process.env.X` in browser codeReplaced with the value at build timeValues live on `import.meta.env`; the mode is `import.meta.env.MODE`, with `DEV` and `PROD` booleansRewrite reads; use `define` only for a named unprefixed value
`%PUBLIC_URL%` in index.htmlBuilt-in variable`%NAME%` works only for keys on `import.meta.env`; unknown ones stay in the HTML as typedDelete it or use `%BASE_URL%`
`import { ReactComponent } from './logo.svg'`Named import returns a React componentAn SVG import is an asset URL; `?raw` and `?url` change that; the typings tip shows a component only as a type overrideAdd 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 listList every API prefix explicitly
`react-scripts test` (Jest)Bundled with the scripts packageVitest offers a Jest-compatible API with documented differencesMove 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.

Checked against: source 6, source 7, source 14, source 15

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

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.

Keep reading

Next step

Have a project in mind?

Tell me about it. A discovery call within 48 hours.